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

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"
}