Guides

Integration Steps

Suggest Edits

🚧

This page is marked as deprecated, but Taxbit will continue supporting customers currently using these solutions. If you’d like to learn more about upgrading to our new React SDK with enhanced Digital W8/W9 support, reach out to our team today.

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:

📘

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

ResponseDescription
IDThe TaxBit internal UUID for the collected tax documentation data.
Document TypeThe type of document.
StatusThe status of the latest Tax Documentation for the account owner.
TIN Verification StatusThe status of the IRS TIN Match in the TaxBit system.
TIN Verification DateThe date of the IRS TIN Match result.

W-8BEN / W-8BEN-E

ResponseDescription
IDThe TaxBit internal UUID for the collected tax documentation data.
Document TypeThe type of document.
StatusThe status of the latest Tax Documentation for the account owner.
IssuesAn array of issues related to the Tax Documentation Submission.
Expiration DateThe 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 5 days ago