Skip to main content
Version: 1.7.1

Webhook

Webhooks are used to notify clients when one of their recipients has completed the W-9. 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 information on Webhooks in TaxBandits.

Configure the Webhook for W-9 Status

  1. Log in to the developer console.

  2. Then navigate to Settings >> Webhooks.

  3. Click the Add Webhook button and choose the Event Type as Form W-9 Status Change while setting up your Webhook URL.

Webhook Settings

Add Webhook

  1. After entering the Callback URL, click on the Submit 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

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission
RequesterobjectRequester information.
    BusinessIdGuidUnique identifier of a business
    BusinessNmStringRequester 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.
    TINTypestringTIN Type of the Requester.
    TINstringTaxpayer Identification Number of the requester.
PayeeRefstringUnique identifier of the recipient
W9StatusstringRecordStatus Status of the W-9
StatusTsstringTimestamp of the W-9 Status.
TINMatchingObjectTIN Matching information.
    StatusStringTIN Matching status.
    StatusTsStringTimestamp of the TIN Matching Status.
    StatusMsgStringStatus message of the TIN Matching.
    ErrorsStringShows the detailed error message.
FormW9RequestTypestringForm W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API methodRequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
PdfUrlstringURL to download the completed W-9.
EmailstringEmail 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 API method RequestByURL
FormDataobject[]Form W-9 details of the recipient.
    Line1NmstringName as shown on the income tax return.
    Line2NmstringBusiness name/disregarded entity name, if different from Line1 Name.
    TINTypestringTIN type of the recipient. Either EIN or SSN
    TINstringRecipient’s TIN.
    AddressobjectRecipient’s complete address
        Address1stringRecipient’s Address 1 (number, street)
        Address2stringRecipient’s Address 2 (apt. or suite no.)
        CitystringRecipient’s City
        StatestringRecipient’s State
        ZipCdstringRecipient’s Zip Code
    FederalTaxClassificationstringU.S. Federal Tax Classification of the person whose name is entered on line 1
    ExemptPayeeCdstringThis code identifies recipients that are exempt from backup withholding.
    ExemptFromFATCAstringThis code identifies recipients that are exempt from reporting under FATCA.
    IsBackUpWHBooleanWhen 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.
Errorsobject[]Shows detailed error information Sample Webhook Response

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": "John Enterprises",   "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": "steve@abcinc.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": "John Enterprises",   "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": "steve@abcinc.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": "John Enterprises",   "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": "steve@abcinc.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}