Integration Steps
It’s time to integrate your application with the Tax Documentation API 🙂.
Before proceeding, you should have satisfied all the prerequisites and configured your environment to call our API.
This document will step you through the following tasks:
- Submit Tax Documentation Data
- Retrieve the Latest Tax Documentation Data
- Retrieve Tax Documentation Data by ID
- Retrieve Tax Documentation Summary
- Generate Tax Documentation Document
- Retrieve a Tax Documentation Document by ID
Note: This guide walks you through how to make API requests on behalf of an account owner.
Submit Tax Documentation Data
The /tax-documentation
endpoint enables you to submit tax documentation data for an account owner.
You can use the following CURL commands to post a tax document for IRS Forms W-9, W-8BEN, or W-8BEN-E. Please remember to update the variables {{base-url}}
,{{base-path}}
, {account_owner_token}
with the appropriate data.
W-9
curl -X POST '{{base-url}}/{{base-path}}/tax-documentation' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}' \
-d '{
"name": "John Wick",
"dba_name": "",
"tax_classification": "INDIVIDUAL",
"address": {
"first_line": "123 Pine St",
"city": "Seattle",
"state_or_province": "WA",
"postal_code": "98000",
"country": "US"
},
"tin": "456456456",
"tin_type": "SSN",
"document_type": "W-9",
"signature": "John Wick",
"signature_timestamp": "2023-02-01T00:00:00.000Z",
"has_certified": true,
"is_not_subject_backup_withholding": true
}'
W-8BEN
curl -X POST '{{base-url}}/{{base-path}}/tax-documentation' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}' \
-d '{
“name”: “John Wick 2”,
“reference_numbers”: “”,
“country”: “GR”,
“permanent_address”: {
“first_line”: “123 Pine St”,
“city”: “Seattle”,
“state_or_province”: “WA”,
“postal_code”: “98000”,
“country”: “GR”
},
“mailing_address”: {
“first_line”: “123 Pine St”,
“city”: “Seattle”,
“state_or_province”: “WA”,
“postal_code”: “98000",
“country”: “US”
},
“ftin”: “667788992",
“document_type”: “W-8BEN”,
“ftin_not_legally_required”: true,
“signature”: “John Wick 2”,
“signature_timestamp”: “2023-02-01T00:00:00.000Z”,
“date_of_birth”: “05/08/1999”,
“has_certified”: true,
“tax_classification”: “INDIVIDUAL”
}'
W-8BEN-E
curl -X POST '{{base-url}}/{{base-path}}/tax-documentation' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}' \
-d '{
"ftin": "667788992",
"name": "John Wick 3",
"country": "GR",
"signature": "John Wick 3",
"document_type": "W-8BEN-E",
"has_certified": true,
"mailing_address": {
"city": "Seattle",
"country": "US",
"first_line": "123 Pine St",
"postal_code": "98000",
"state_or_province": "WA"
},
"permanent_address": {
"city": "Seattle",
"country": "GR",
"first_line": "123 Pine St",
"postal_code": "98000",
"state_or_province": "WA"
},
"reference_numbers": "",
"tax_classification": "CORPORATION",
"signature_timestamp": "2023-02-01T00:00:00.000Z",
"ftin_not_legally_required": true
}'
A sample W-9 tax-documentation post response will include the entire body, an attached ID, and hopefully a 200 status code 🙂. We recommend storing the ID since you will use it in the Retrieve Tax Documentation Data by ID section.
{
"name": "John Wick",
"dba_name": "",
"tax_classification": "INDIVIDUAL",
"address": {
"first_line": "123 Pine St",
"city": "Seattle",
"state_or_province": "WA",
"postal_code": "98000",
"country": "US"
},
"tin": "456456456",
"tin_type": "SSN",
"document_type": "W-9",
"signature": "John Wick",
"signature_timestamp": "2023-02-01T00:00:00.000Z",
"has_certified": true,
"is_not_subject_backup_withholding": true,
"id": "3953ef04-f3de-482f-b9e3-18c6ac42a3ab"
}
Retrieve Tax Documentation Data by ID
The /tax-documentation/{id}
endpoint will enable you to get tax documentation data by the document ID. The ID is a path parameter in our URL, and you can get this ID from the response to the POST request you made in the Submit Tax Documentation Data section.
You can use the CURL command below to retrieve tax documentation data by ID:
curl -X GET '{{base-url}}/{{base-path}}/tax-documentation/{id}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}'
The tax-documentation by ID endpoint returns a response like the example below:
{
"name": "John Wick",
"dba_name": "",
"tax_classification": "INDIVIDUAL",
"address": {
"first_line": "123 Pine St",
"city": "Seattle",
"state_or_province": "WA",
"postal_code": "98000",
"country": "US"
},
"tin": "456456456",
"tin_type": "SSN",
"document_type": "W-9",
"signature": "John Wick",
"signature_timestamp": "2023-02-01T00:00:00.000Z",
"has_certified": true,
"is_not_subject_backup_withholding": true,
"id": "3953ef04-f3de-482f-b9e3-18c6ac42a3ab"
}
Retrieve the Latest Tax Documentation Data
The /tax-documentation
endpoint will enable you to get the latest tax documentation data. For example, if you POST a document of type W-9 and then POST another document of type W-8BEN-E, this endpoint will return the W-8BEN-E tax document.
You can use the CURL command below to retrieve the latest tax documentation data:
curl -X GET '{{base-url}}/{{base-path}}/tax-documentation' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}'
The latest tax-documentation endpoint returns a response like the example below:
{
"ftin": "667788992",
"name": "John Wick 3",
"country": "GR",
"signature": "John Wick 3",
"document_type": "W-8BEN-E",
"has_certified": true,
"mailing_address": {
"city": "Seattle",
"country": "US",
"first_line": "123 Pine St",
"postal_code": "98000",
"state_or_province": "WA"
},
"permanent_address": {
"city": "Seattle",
"country": "GR",
"first_line": "123 Pine St",
"postal_code": "98000",
"state_or_province": "WA"
},
"reference_numbers": "",
"tax_classification": "CORPORATION",
"signature_timestamp": "2023-02-01T00:00:00.000Z",
"ftin_not_legally_required": true,
"id": "c5b2c915-da38-4c10-87ce-0a391971118d"
}
Retrieve Tax Documentation Summary
The /tax-documentation/summary
endpoint will enable you to get a summary of the tax documentation data. The response will vary depending on the document type:
W-9
Response | Description |
---|---|
ID | The TaxBit internal UUID for the collected tax documentation data. |
Document Type | The type of document. |
Status | The status of the latest Tax Documentation for the account owner. |
TIN Verification Status | The status of the IRS TIN Match in the TaxBit system. |
TIN Verification Date | The date of the IRS TIN Match result. |
W-8BEN / W-8BEN-E
Response | Description |
---|---|
ID | The TaxBit internal UUID for the collected tax documentation data. |
Document Type | The type of document. |
Status | The status of the latest Tax Documentation for the account owner. |
Issues | An array of issues related to the Tax Documentation Submission. |
Expiration Date | The expiration date of the latest Tax Documentation for an account owner. |
You can use the CURL command below to retrieve the tax documentation summary:
curl -X GET '{{base-url}}/{{base-path}}/tax-documentation/summary \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}'
The latest tax-documentation endpoint returns a response like the example below:
W-9
{
"document_type": "W-9",
"status": "VALID",
"tin_verification_status": "PENDING",
"tin_verification_date": "2025-12-31T00:00:00.000Z",
"id": "1d3b8eeb-53ed-41e9-9c16-1a591c014a0b"
}
W-8BEN / W-8BEN-E
{
"document_type": "W-8BEN-E",
"status": "INVALID",
"issues": [
{
"issue_type": "US_MAILING_ADDRESS",
"issue_status": "OPEN",
"curing_status": "OPEN",
"resubmission_status": "NOT_APPLICABLE"
}
],
"expiration_date": "2027-01-01T00:00:00.000Z",
"id": "78ec197c-4cf7-4394-a265-2a46bbacf99a"
}
Generate Tax Documentation Document
The /tax-documentation/document
endpoint will enable you to generate the latest W-9, W-8BEN, or W-8BEN-E PDF document for an Account Owner.
You can use the CURL command below to generate the latest tax document:
curl -X GET '{{base-url}}/{{base-path}}/tax-documentation/document' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}'
The response will include the job ID and other related information. We recommend storing the job ID since you will use it in the Retrieve a Tax Documentation Document by ID section to get a PDF document by ID.
{
"id": "e3030559-fe55-40a6-8eb0-9f24caeec150",
"status": "IN_PROGRESS",
"type": "W-9",
"created_date": "2023-05-08T19:05:41.403Z"
}
Retrieve a Tax Documentation Document by ID
The /tax-documentation/document/{document-id}
endpoint will enable you to retrieve a W-9, W-8BEN, or W-8BEN-E PDF by document ID for an Account Owner. The ID is a path parameter in our URL, and you can get this from the response to the POST request you made in the previous section.
You can use the CURL command below to retrieve a document by ID:
curl -X GET '{{base-url}}/{{base-path}}/tax-documentation/document/{document-id}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {account_owner_token}'
The response will include the PDF download URL and other related information.
{
"id": "e3030559-fe55-40a6-8eb0-9f24caeec150",
"status": "FINISHED",
"type": "W-9",
"created_date": "2023-05-08T19:05:41.403Z",
"url": "https://devs-staging-useast1-documents-v2.s3.us-east-1.amazonaws.com/5542ad15-488d-4084-826c-d4d735b901a5/74138216-8c45-4915-b7c8-d4b6b1af671d/W9/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIA5I3RSXCQ7RCJTMOC%2F20230508%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230508T191046Z&X-Amz-Expires=600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEwaCXVzLWVhc3QtMSJIMEYCIQDStol0glQWuImqRiR1MzmYgktcphZtAdVO4ekbO1hq%2FwIhAP20TpRa%2FTZIEmGhbJHBo0XTK1BmMD1IO6PT7JXRXm2FKs8DCGQQARoMOTEyMzgxODg0NTc3Igy63LWLIQ70bd0wGeMqrAMDrB7JbUIsKyNc%2F4H9BTWOqr886%2Fkbm2FI7m8dD0NR0MUgfaBvY9gb10xlmDg3LJFu8ZxiQJvZGxILY3s55SgrIJuOvHm5Up5W%2Fg7xwXvrVxXj1%2Fcpb2w4EcHBFjw%2B3uvU96JP5sW3%2BOKiTFsI8nAuMA9HHtg6F3JAhWY8vRufH%2FqB1x6PEH5fdVjgcdhOFYtaGmS6M2hDfFxcvUt8844FTr8YTZtJznzw3s7vvjISi33oGz41zx%2Byejcvkj9DVBaEbL%2FNk%2Fq0PJ6HS9Umgdm2OZACRvDv2CRWycKcxUuTSyA6WtS1BDDibVpqPKnYjEEY3EPWcluQTO7UB1gYQ3AZPNJG1fyJz13GAFZF%2BiROtqG0jogzCbYfrVQ8VxeoS2%2FBIo9M1eVH%2F%2FBu9PN8WsTpBZgQKkRlj5Se9QVVTpdf3i%2BJos0QLvCgUWtdsmKCuPH03WPxF0hCwkNZKIcIzbpaoWLXiFqMIcAxSFJACfen92ccsGCMIytT09qIaXttnQuDPTt1G4sUij%2BFdS62h0omK%2BwwiaKyQ7tmynQ84%2BRF5eFNLMKlzDz4ynG6ojDFj%2BWiBjqdAX7GqfIDGfs7MihOyMwQGi9wOsdnYkLjLRW80dkfVSvYCHFT3GpYmSAJecQdL%2BIwGq1Fm1C7F2vusWegNcUD%2F%2FCmibO7JFdqsfroZ3L6RkEwM76NSmBY3hrFvkqAHZNS%2FsbyYJAkATjOqSVWHcUExoZRFbdhV0LDCiSO8wTvCJY9ug0Pv31GLG1diu91rmSsjmoV8ch2yqK2YGEM6QE%3D&X-Amz-Signature=cc34c99d132812a13ca5331ccb21162e5427ab9a78437794dfa7bf50e776f486&X-Amz-SignedHeaders=host&versionId=yHyovlOrcwfLf8P0foQxmW2yfntOyV3k&x-id=GetObject"
}
Updated 3 months ago