Webhook
Webhooks are used to notify clients regarding the status of W-9 completion by the recipients. The webhook payload includes W-9 data such as the recipient’s name, address, EIN/SSN, as well as the link to download the completed form.
Go to Webhooks for more information.
Configure the Webhook for W-9 Status
-
Log in to the developer console.
- Sandbox Console URL: sandbox.taxbandits.com
- Live Console URL: console.taxbandits.com
-
Then navigate to Settings >> Webhooks.
-
Click the Add Webhook button and choose the Event Type as Form W-9 Status Change while setting up your Webhook URL.
- After entering the Callback URL, click on the Save button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.
Response Body
| Field | Type | Description |
|---|---|---|
| SubmissionId | Guid | A Unique identifier of a submission |
| Requester | object | Requester information. |
| BusinessId | Guid | A Unique identifier of a business |
| BusinessNm | String | Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned. |
| TINType | string | TIN Type of the Requester. |
| TIN | string | Taxpayer Identification Number of the requester. |
| PayeeRef | string | A Unique identifier of the recipient |
| W9Status | string | RecordStatus Status of the W-9 |
| StatusTs | string | Timestamp of the W-9 Status. |
| TINMatching | Object | TIN Matching information. |
| Status | String | TIN Matching status. |
| StatusTs | String | Timestamp of the TIN Matching Status. |
| StatusMsg | String | Status message of the TIN Matching. |
| Errors | object[] | Shows the detailed error message. |
| FormW9RequestType | string | Form W-9 requested Type.
|
| PdfUrl | string | URL to download the completed W-9. Note: This URL will expire in 24 hours. |
| string | Email address of the recipient. This is the email to which the W-9 request was sent.(The value will be null if the Form W-9 was requested using the RequestByUrl method). | |
| FormData | object | Form W-9 details of the recipient. |
| Line1Nm | string | Name as shown on the income tax return. |
| Line2Nm | string | Business name/disregarded entity name, if different from Line1 Name. |
| TINType | string | TIN type of the recipient (EIN or SSN) |
| TIN | string | Recipient’s TIN. |
| Address | object | Recipient’s complete address |
| Address1 | string | Recipient’s Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. |
| Address2 | string | Recipient’s Address 2 (suite or apartment number). This will be pre-filled on the Form. |
| City | string | Recipient’s City |
| State | string | Recipient’s State |
| ZipCd | string | Recipient’s Zip Code |
| FederalTaxClassification | string | U.S. Federal Tax Classification of the person whose name is entered on line 1 |
| ExemptPayeeCd | string | This code identifies recipients that are exempt from backup withholding. |
| ExemptFromFATCA | string | This code identifies recipients that are exempt from reporting under FATCA. |
| IsBackUpWH | Boolean | When true, identifies the recipient is subject to backup withholding. The completed Form W-9 PDF will have the item 2 under Part II crossed out. When false, identifies the recipient is not subject to backup withholding. |
| Errors | Object[] | Detailed error information. |
| Id | string | Error ID number. This ID is assigned by TaxBandits and it is unique for each error. |
| Name | string | Name of the errored node. |
| Message | string | Shows the error message |
Scenario 1: The recipient has completed Form W-9, and the status has been changed to “Completed and TIN Matching Inprogress”. It will be notified to clients via Webhook. PdfUrl is provided to download the completed form W-9.
{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "Snowdaze LLC",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -04:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"StatusMsg": null,
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "sample@bodeem.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}
Scenario 2: The recipient has completed Form W-9, and the status has been changed to “Completed” and TIN Matching is successful. It will be notified to clients via Webhook. PdfUrl is provided to download the completed form W-9.
{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "Snowdaze LLC",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED",
"StatusTs": "2021-02-19 14:36:28 -04:00",
"TINMatching": {
"Status": "Success",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"StatusMsg": null,
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "sample@bodeem.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}
Scenario 3: The recipient has completed Form W-9, and the status has been changed to “Invalid” because of the TIN Matching failure. It will be notified to clients via Webhook. PdfUrl is provided to download the completed form W-9.
{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "Snowdaze LLC",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "Invalid",
"StatusTs": "2021-02-19 14:36:28 -04:00",
"TINMatching": {
"Status": "Failed",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"StatusMsg": null,
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "sample@bodeem.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}