Version: 1.7.3

Webhook

Use webhooks to receive automatic status updates when a recipient opens, completes, or submits a W-9 form. Instead of checking the status manually, TaxBandits sends the update directly to your callback URL.

Here are the steps to configure webhooks for Form W-9 status

1. Log in to the Developer Console

Go to the appropriate console based on your environment:

Environment	URL
Sandbox	`sandbox.taxbandits.com`
Live	`console.taxbandits.com`

2. Go to Webhook Settings

From the Developer Console, navigate to Settings > Webhooks. Then click Add Webhook.

3. Select the Event Type

Choose the event type: Form W-9 Status Change. This event notifies your system whenever the recipient’s W-9 form status changes.

4. Add Your Callback URL

Enter the callback URL where TaxBandits should send webhook notifications.

Your callback URL must be:

Publicly accessible
Able to receive POST requests
Configured to return HTTP 200

When TaxBandits sends a sample or live webhook payload, your server must return an HTTP status code 200. If your server does not return 200, the webhook will become inactive. You can retry the sample payload from the Developer Console to reactivate it.

5. Save the Webhook

After saving, TaxBandits generates a unique WebhookRef for that callback URL.

Store this WebhookRef in your system. You can use it later to decide which callback URL should receive updates for a specific Form W-9 request.

6. Use WebhookRef in API Requests

When making Form W-9 API requests, such as FormW9/RequestByUrl, you can include the WebhookRef.

If you include WebhookRef, updates will be sent to the callback URL linked to that reference.

If you do not include WebhookRef, updates will be sent to your default callback URL.

7. Receive Status Updates

Once configured, TaxBandits sends webhook notifications whenever the Form W-9 status changes.

The webhook may include:

Recipient name
Address
TIN
Form type
Form status
TIN Matching status
Submission timestamp
Secure PDF download link

By default, the webhook response will include the recipient’s TIN. If you prefer not to include the TIN, you can adjust this preference in the console. See how

Response Body

Field	Type	Description
SubmissionId	Guid	A Unique identifier of a submission
WebhookRef	Guid	A unique identifier of the Webhook that TaxBandits generates against each Callback URL when adding it in the console site. If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
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.
FirstNm	string	First Name of the Individual
MiddleNm	string	Middle Name of the Individual
LastNm	string	Last Name of the individual
Suffix	string	Suffix of the Individual
TINType	string	TIN Type of the Requester.
TIN	string	Taxpayer Identification Number of the requester.
DBAId	Guid	Unique Identifier for the DBA.
DBARef	Guid	Unique identifier for each DBA. This identifier can be used in future references of the DBA in the API
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. URL_API - Form W-9 was requested using the RequestByURL method. Email_API - Form W-9 was requested using the RequestByEmail method.
PdfUrl	string	URL to download the completed W-9. Note: This URL will expire in 24 hours. This URL is encrypted by default. Follow these steps to decrypt the URL. If you'd like to have a decrypted URL by default, you can configure the preferences in Developer Console -> Settings -> W-9/W-8 Preferences.
Email	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.
FirstNm	string	First Name of the Individual
MiddleNm	string	Middle Name of the Individual
LastNm	string	Last Name of the individual
Suffix	string	Suffix of the Individual
TINType	string	TIN type of the recipient
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
Country	string	Recipient's country code. Refer to Static values. Size Range: 2 Allowed values "AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"
AccountNum	string	Recipient’s account number. You can use this field to enter any identification number you have for the recipient.
FederalTaxClassification	string	U.S. Federal Tax Classification of the person whose name is entered on line 1
IsLine3b	Boolean	If TRUE, identifies that the recipient is Either a partnership, trust or estate that has foreign partners, owners, or beneficiaries and the recipient is providing this form to a partnership, trust, or estate, in which they have an ownership interest. (or) Received a Form W-8 from any partner, owner, or beneficiary establishing foreign status (or) Received a Form W-9 from any partner, owner, or beneficiary that has checked the box on line 3b.
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.
IsDAExemptBroker	Boolean	When true, identifies the recipient is exempt from information reporting as a U.S. digital asset broker within the meaning of Regulations section 1.6045-1(g)(4)(i)(A)(1)
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: Recipient completes Form W-9, status changes to ‘Completed and TIN Matching In Progress’. You receive a webhook notification with the status update. PdfUrl is included to download the completed form.

{
  "SubmissionId": "75838ff2-8e57-49eb-8fa0-3d8d7ca4c006",
  "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
  "Requester": {
    "BusinessId": "7b0e44d7-17f1-4dc8-87a2-5e4d18b10929",
    "PayerRef": "Pay140054",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "Suffix": null,
    "TINType": "EIN",
    "TIN": "86-5923037",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "pay2147",
  "RecipientId": "17c639fe-14f2-46ca-9e74-a510a47eb1d5",
  "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
  "StatusTs": "2024-07-30 05:04:35 -04:00",
  "TINMatching": {
    "Status": "ORDER_CREATED",
    "StatusTs": "2024-07-30 05:04:36 -04:00",
    "StatusMsg": null,
    "Errors": null
  },
  "FormW9RequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/7cc37d30-d645-408d-986f-6ee79b91adfc.Pdf",
  "Email": null,
  "FormData": {
    "Line1Nm": "michal k william Jr",
    "Line2Nm": null,
    "FirstNm": "michal",
    "MiddleNm": "k",
    "LastNm": "william",
    "Suffix": "Jr",
    "TINType": "SSN",
    "TIN": "665-74-5684",
    "Address": {
      "Address1": "71 SAINT NICHOLAS DR",
      "Address2": null,
      "City": "NORTH POLE",
      "State": "AK",
      "ZipCd": "99705-7752"
    },
    "AccountNum": "42526325",
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false,
    "IsDAExemptBroker": true
  },
  "Errors": null
}

Scenario 2: Recipient completes Form W-9, status changes to ‘Completed with successful TIN Matching’. Webhook notifies your system. PdfUrl included for download.

{
  "SubmissionId": "75838ff2-8e57-49eb-8fa0-3d8d7ca4c006",
  "WebhookRef": null,
  "Requester": {
    "BusinessId": "7b0e44d7-17f1-4dc8-87a2-5e4d18b10929",
    "PayerRef": "Pay140054",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "LastNm": null,
    "MiddleNm": null,
    "Suffix": null,
    "TINType": "EIN",
    "TIN": "XX-XXX3037",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "pay2147",
  "RecipientId": "17c639fe-14f2-46ca-9e74-a510a47eb1d5",
  "W9Status": "COMPLETED",
  "StatusTs": "2024-07-30 05:19:49 -04:00",
  "TinMatching": {
    "Status": "SUCCESS",
    "StatusTs": "2024-07-30 05:19:48 -04:00",
    "StatusMsg": null,
    "Errors": null
  },
  "FormW9RequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/7cc37d30-d645-408d-986f-6ee79b91adfc.Pdf",
  "Email": null,
  "FormData": {
    "Line1Nm": null,
    "Line2Nm": null,
    "FirstNm": "michal",
    "LastNm": "william",
    "MiddleNm": "k",
    "Suffix": "Jr",
    "TINType": "SSN",
    "TIN": "665-74-5684",
    "Address": {
      "Address1": "71 SAINT NICHOLAS DR",
      "Address2": null,
      "City": "NORTH POLE",
      "State": "AK",
      "ZipCd": "99705-7752"
    },
    "AccountNum": "42526325",
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false,
    "IsDAExemptBroker": true,
    "OtherDescription": null
  },
  "Errors": null
}

Scenario 3: Recipient completes Form W-9, status changes to INVALID due to TIN Matching failure. Webhook notification sent. PdfUrl still provided for reference.

{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"WebhookRef": null,
"Requester": {
  "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
  "BusinessNm": "Snowdaze LLC",
  "TINType": "EIN",
  "TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "INVALID",
"StatusTs": "2025-02-19 14:36:28 -04:00",
"TINMatching": {
  "Status": "Failed",
  "StatusTs": "2025-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"
  },
  "AccountNum": "42526326",
  "FederalTaxClassification": "C Corporation",
  "IsLine3b": true,
  "ExemptPayeeCd": "5",
  "ExemptFromFATCA": "E",
},
"Errors": null
}

Scenario 4: The recipient has completed Form W-9 but has not provided the TIN, so the status has changed to ‘AWAITING_TIN_CERTIFICATE’. A reminder will be sent via Webhook before the expiration date. PdfUrl is provided to download the completed Form W-9.

{
  "SubmissionId": "75838ff2-8e57-49eb-8fa0-3d8d7ca4c006",
  "WebhookRef": null,
  "Requester": {
    "BusinessId": "7b0e44d7-17f1-4dc8-87a2-5e4d18b10929",
    "PayerRef": "Pay140054",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "LastNm": null,
    "MiddleNm": null,
    "Suffix": null,
    "TINType": "EIN",
    "TIN": "XX-XXX3037",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "pay2147",
  "RecipientId": "17c639fe-14f2-46ca-9e74-a510a47eb1d5",
  "W9Status": "AWAITING_TIN_CERTIFICATE",
  "ExpireDate": "07-30-2024",
  "StatusTs": "2024-07-30 05:19:49 -04:00",
  "TinMatching": null,
  "FormW9RequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/7cc37d30-d645-408d-986f-6ee79b91adfc.Pdf",
  "Email": null,
  "FormData": {
    "Line1Nm": null,
    "Line2Nm": null,
    "FirstNm": "michal",
    "LastNm": "william",
    "MiddleNm": "k",
    "Suffix": "Jr",
    "TINType": "SSN",
    "TIN": "665-74-5684",
    "Address": {
      "Address1": "71 SAINT NICHOLAS DR",
      "Address2": null,
      "City": "NORTH POLE",
      "State": "AK",
      "ZipCd": "99705-7752"
    },
    "AccountNum": "42526325",
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false,
    "IsDAExemptBroker": true,
    "OtherDescription": null
  },
  "Errors": null
}

Scenario 5: No reference ID has been passed in the WebhookRef node of the request. The recipient has completed Form W-9, has provided the ITIN and TIN Matching as true and Status is updated as ‘SUCCESS’. The payload will be posted to the default Callback URL, i.e., Callback URL 1.

{
  "SubmissionId": "617140eb-7de8-4259-98ac-14776eef249b",
  "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
  "Requester": {
    "BusinessId": "51cd2f9f-046c-47c4-988f-7f83c2bdd3ee",
    "PayerRef": null,
    "BusinessNm": "James Smith",
    "FirstNm": "James",
    "MiddleNm": null,
    "LastNm": "Smith",
    "Suffix": null,
    "TINType": "SSN",
    "TIN": "XXX-XX-6767",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "Pe6999",
  "RecipientId": "22971d38-4349-4ee0-9e1b-97ab82a740eb",
  "W9Status": "COMPLETED",
  "ExpireDate": null,
  "StatusTs": "2025-10-12 00:37:23 -04:00",
  "TINMatching": {
    "Status": "SUCCESS",
    "StatusTs": "2025-10-12 00:37:23 -04:00",
    "StatusMsg": null,
    "Errors": null
  },
  "FormW9RequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/b0c4e691-89dd-45d9-8aab-160ae31eec0a.Pdf",
  "Email": null,
  "FormData": {
    "Line1Nm": "Henry David",
    "Line2Nm": "Technologic",
    "FirstNm": "Henry",
    "MiddleNm": null,
    "LastNm": "David",
    "Suffix": null,
    "TINType": "ITIN",
    "TIN": "XXX-XX-7734",
    "Address": {
      "Address1": "2603 Kinsey Road",
      "Address2": "Main Street",
      "City": "DOTHAN",
      "State": "AL",
      "ZipCd": "36303",
      "Country": "US"
    },
    "AccountNum": null,
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false,
    "IsDAExemptBroker": true,
  },
  "Errors": null
}

W-9/W-8 Automation

1099 Automation

TIN Matching

W-2 Automation

941/940 Automation

1098-T Automation

ACA Automation

Extension Automation

1042-S Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Healthcare Market Research Platforms

Webhook

1. Log in to the Developer Console​

2. Go to Webhook Settings​

3. Select the Event Type​

4. Add Your Callback URL​

5. Save the Webhook​

6. Use WebhookRef in API Requests​

7. Receive Status Updates​

Response Body​

Scenario 1: Recipient completes Form W-9, status changes to ‘Completed and TIN Matching In Progress’. You receive a webhook notification with the status update. PdfUrl is included to download the completed form.​

Scenario 2: Recipient completes Form W-9, status changes to ‘Completed with successful TIN Matching’. Webhook notifies your system. PdfUrl included for download.​

Scenario 3: Recipient completes Form W-9, status changes to INVALID due to TIN Matching failure. Webhook notification sent. PdfUrl still provided for reference.​

Scenario 4: The recipient has completed Form W-9 but has not provided the TIN, so the status has changed to ‘AWAITING_TIN_CERTIFICATE’. A reminder will be sent via Webhook before the expiration date. PdfUrl is provided to download the completed Form W-9.​

Scenario 5: No reference ID has been passed in the WebhookRef node of the request. The recipient has completed Form W-9, has provided the ITIN and TIN Matching as true and Status is updated as ‘SUCCESS’. The payload will be posted to the default Callback URL, i.e., Callback URL 1.​