Version: 1.7.3

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.

Webhook Settings

Add Webhook

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.
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. Email_UI - Form W-9 was requested from the TaxBandits UI application.
PdfUrl	string	URL to download the completed W-9. Note: This URL will expire in 24 hours.
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 (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
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.
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": "75838ff2-8e57-49eb-8fa0-3d8d7ca4c006",
  "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
  },
  "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": "75838ff2-8e57-49eb-8fa0-3d8d7ca4c006",
  "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,
    "OtherDescription": null
  },
  "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"
  },
  "AccountNum": "42526326",
  "FederalTaxClassification": "C Corporation",
  "IsLine3b": true,
  "ExemptPayeeCd": "5",
  "ExemptFromFATCA": "E"
},
"Errors": null
}

W-9 Automation

BOIR Automation

TIN Matching

1099 Automation

941/940 Automation

W-2 Automation

ACA Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Supported Forms