WhCertificate

If you are making payments to anyone other than the employees on your payroll, you will need to file a Form 1099 for this individual. The Form 1099 you must file will vary depending on the type of payments you make. For example, if you are paying an independent contractor for their services, you should file Form 1099-NEC.

If your recipient is a US resident or entity, regardless of which Form 1099 you are required to file, as a payer you must collect a Form W-9 (Request for Taxpayer Identification Number and Certification) to confirm their name, address, and taxpayer identification number (TIN).

If the recipient fails to provide the Form W-9 with correct information, you are required to withhold 24% of the payment and deposit with the IRS. Also, W-9 has the place where the vendor can specify if the payer must withhold as per the IRS direction given to them. This is called backup withholding.

If your recipient is a Foreign individual, you are not required to file a Form 1099. Instead, you must collect Form W-8BEN (Certificate of Foreign Status of Beneficial Owner for United States Tax Withholding and Reporting (Individuals)) to verify their country of residence and to certify that they qualify for a lower rate of tax withholding. If the recipient fails to submit Form W-8BEN you are required to withhold 30% (Full Tax Rate) on their payments.

The TaxBandits application and API is equipped to handle the many situations you may face when working with individuals and vendors outside your organization. Let’s discuss the complete solution that TaxBandits offers for requesting, presenting, and acquiring a signed W-9 or W-8BEN from your recipients.

TIN Matching

You can opt for TIN Matching service when requesting the Form from your recipient. Once the recipient completes the Form W-9, TaxBandits will validate the Recipient Name and TIN given in the Form W-9 against the IRS records and communicate the results via Webhook. It will take 24 hours for the IRS to process the data and return the statuses.

TIN Matching will not be applicable for the recipients who complete Form W-8BEN.

If the Recipient Name and TIN combination does not match with the IRS records, you can request a new Form W-9 from the recipient.

Note: TIN Matching prevents you from entering the wrong TINs on the 1099s. Therefore, it will help you avoid hefty penalties and expenses from filing invalid 1099 Forms.

Get

This method will return the completed W-9 or W-8BEN of a particular recipient. The response will have the information such as the Name, Address, Country of citizenship and TIN number along with the link to download the completed Form W-9 or W-8BEN.

Key Points

• Only W-9s or W-8BENs with the completed status can be retrieved using the Get method. If the status of the form is other than complete, it will not be returned.

• If you do not supply the BusinessId or TIN or PayerRef in the request, then the W-9 or W-8BEN that matches the PayeeRef linked to the default business will be retrieved.

• If there are multiple forms for the same PayeeRef, the last completed form will be retrieved.

GET WhCertificate/Get

Request Body

Field	Type	Description
PayeeRef	String	A unique identifier for each recipient completing the Form W-9 and W-8BEN. This identifier will be used in future references of the recipient in the API. Size Range: 1-50
BusinessId	Guid	Optional TaxBandits Unique Business Identifier. This ID is generated by `TaxBandits after you create a business in your account using the Business endpoint.If you do not supply the BusinessId in the request, then the W-9 or W-8BEN that matches the PayeeRef linked to the default business will be retrieved. (First business created in your account).
TIN	String	Optional Taxpayer Identification Number. Use this as an alternative for BusinessId. Size Range: 9-11 Allowed values: "EIN", "SSN" (Including hyphen)
PayerRef	String	Optional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL. Size Range: 1-50

Response Body

Field	Type	Description
FormType	String	Type of Form (W-9 or W-8BEN).
FormW9	Object	Contains Form W-9 Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
PayerRef	String	An unique identifier of the business. Assigned by the client.
BusinessNm	String	Business Name of the requester. 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	Unique identifier of the recipient
RecipientId	Guid	An unique ID generated by TaxBandits after the W-9 is completed. Clients can use this ID to file Form 1099s for this recipient.
W9Status	String	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.
Errors	String	Shows the detailed error message.
FormW9RequestType	String	Form W-9 requested Type. COMMON_URL_API - Form W-9 was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-9
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 API method RequestByURL
FormData	Object	Form W-9 data 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. Either EIN or SSN
TIN	string	Recipient’s TIN
Address	Object	Recipient’s complete address
Address1	string	Recipient’s Address 1 (number, street)
Address2	string	Recipient’s Address 2 (apt. or suite no.)
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 the recipient is exempt from backup withholding
ExemptFromFATCA	string	This code identifies recipients that are exempt from reporting under FATCA.
Errors	Object	Shows detailed error information.
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.
FormW8Ben	Object	Form W-8BEN Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
PayerRef	String	An unique identifier of the business. Assigned by the client.
BusinessNm	String	Business Name of the requester. 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	Unique identifier of the recipient
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status.
FormW8BENRequestType	String	Form W-8BEN requested Type. COMMON_URL_API - Form W-8BEN was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-8BEN.
Email	String	Email Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL.
FormData	Object	Form W-8BEN data of the recipient.
NmOfIndividual	string	Name of the Foreign Individual.
CitizenOfCountry	string	Recipient country of citizenship.
USTINType	string	TIN type of the recipient. Either SSN or ITIN.
USTIN	string	Recipient’s TIN
ForeignTIN	string	Foreign TIN of the recipient.
IsFTINNotLegallyRequired	Boolean	When TRUE, Identifies that benificial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence.
DOB	string	Date of Birth of the recipient
PermanentAddress	Object	Recipient’s permanent address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
MailingAddress	Object	Recipient’s mailing address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
TaxTreatyBenefits	Object	Tax Treaty Benefits.
BeneficiaryCountry	string	Country where the recipient claim to be a resident for income tax treaty purposes.
ClaimingProvArticlePara	string	Article and paragraph of the treaty benefits.
RateOfWH	string	Rate of Withholding.
TypeOfIncome	string	Type of income for which recipient claiming the treaty benefits.
AdditionalConditions	string	Additional conditions from the tax treaty benefits.
Signature	Object	Signature of the recipient.
SignerNm	string	Name of the signer.
Errors	Object	Shows detailed error information.

Get Request 1 : Get form details with just Recipient Payee Reference.

WhCertificate/Get?PayeeRef=Pe123451234

Get Request 2 : Get form details with Recipient Payee Reference and BusinessID.

WhCertificate/Get?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Get Request 3 : Get form details with Recipient Payee Reference and Business TIN.

WhCertificate/Get?PayeeRef=Pe123451234&TIN=22-2222222

Get Request 4 : Get form details with Recipient Payee Reference and Payer Reference.

WhCertificate/Get?PayeeRef=Pe123451234&PayerRef=Me1231231233

Response for W8-BEN :

{
 "FormType": "W8Ben",
 "FormW9": null,
 "FormW8Ben": {
   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
   "Requester": {
     "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
     "PayerRef": null,
     "BusinessNm": "John Enterprises",
     "TINType": "EIN",
     "TIN": "22-2222222"
   },
   "PayeeRef": "7484391234545",
   "W8BENStatus": "COMPLETED",
   "StatusTs": "2021-02-19 14:36:28 -05:00",
   "FormW8BENRequestType": "URL_API",
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "steve@abcinc.com",
   "FormData": {
     "NmOfIndividual": "Joseph Smith",
     "CitizenOfCountry": "Canada",
     "USTINType": "SSN",
     "USTIN": "111-11-1111",
     "ForeignTIN": null,
     "IsFTINNotLegallyRequired": true,
     "DOB": "07/08/1990",
     "PermanentAddress": {
       "Address": "123 E. Main St",
       "City": "Rock Hill",
       "State": "SC",
       "Country": "USA",
       "ZipCd": "29730"
     },
     "MailingAddress": {
       "Address": null,
       "City": null,
       "State": null,
       "Country": null,
       "ZipCd": null
     },
     "TaxTreatyBenefits": {
       "BeneficiaryCountry": "Canada",
       "ClaimingProvArticlePara": "VII",
       "RateOfWH": "27.50",
       "TypeOfIncome": "Royalties",
       "AdditionalConditions": null
     },
     "Signature": {
       "SignerNm": "Joseph"
     }
   },
   "Errors": null
 },
 "Errors": null
}

Response for FormW9 :

{
 "FormType": "FormW9",
 "FormW9": {
   "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
   "Requester": {
     "BusinessId": "fb6ddd28-ad30-4fc2-bd17-38a937f2aa81",
     "BusinessNm": "John Enterprises",
     "PayerRef": null,
     "TINType": "EIN",
     "TIN": "XX-XXX2222"
   },
   "PayeeRef": "Pe123451234",
   "RecipientId": "sdf3ccee-10d8-4eb4-ab81-234234c9636",
   "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
   "StatusTs": "2021-06-24 10:40:21 -04:00",
   "TINMatching": {
     "Status": "ORDER_CREATED",
     "StatusTs": "2021-06-24 10:40:21 -04:00",
     "StatusMsg": null,
     "Errors": null
   },
   "FormW9RequestType": "Email_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": "XX-XXX1111",
     "Address": {
       "Address1": "123 E. Main St",
       "Address2": "Suite 400",
       "City": "Rock Hill",
       "State": "SC",
       "ZipCd": "29730"
     },
     "FederalTaxClassification": "C Corporation",
     "ExemptPayeeCd": "5",
     "ExemptFromFATCA": "F",
     "IsBackUpWH": false
   },
   "Errors": null
 },
 "FormW8Ben": null,
 "Errors": null
}

RequestByUrl

To complete the Form W-9 or W-8BEN, TaxBandits will supply the URL. This URL can be opened on its own or embedded as an Iframe into a web page or native app. To get the URL, you will have to send a request to our API with a unique Payee Reference such as the vendor id, contractor number, or a random number or even an email address (This will be used to identify the recipient for future references) and some business identifier (TaxBandits Business Id or TIN).

This is the recommended method to use when you have a portal for your vendors, where you can place a link to collect the W9 or W8BEN information. Each vendor who logs in will get a unique URL embedded page to complete their W9 or W-8BEN.

You can customize the logo, callback redirection URLs in the request.

How does this work?

1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token.Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

2. The second step is to call the [POST] WhCertificate/RequestByUrl endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page. You will need to supply the following parameters:

   • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API).
   • Payee Reference (Unique information that identifies the Recipient). The Payee Reference can be anything that uniquely identifies the recipient such as their Vendor id, contractor number, or a random number, or even the recipient email address (This will be used to identify the recipient for future references).
   • Business Identifier Business Id or TIN or PayerRef(Optional) - This is used to identify and save the W9/W-8BEN under a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits and retrieving the Business Id. In TaxBandits, you can uniquely identify a business using either its TIN or the TBS-generated Business Id or PayerRef (Unique payer identifier assigned by you while requesting the payer information using the endpoint Business/RequestByURL). You can also define a ‘Default Business’ (First business created in your account) in the TaxBandits Application and skip sending the Business Identifier along with the request.
   • Recipient Name and Address (Optional) - If you want to pre-fill the Name and Address of the recipient on the W-9/W-8BEN form, you can send them as a parameter in the request.
   • Business Logo and Callback URLs (Optional) - You can add the business logo on the Form W-9/Form W8-BEN completion page and also set the callback redirection for recipient form completion/cancel.

3. TaxBandits will generate a unique URL and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the recipients to click. When clicked, the recipient will be provided with the option to choose the Form W-9 or W-8BEN based on their nationality, resident status etc. Once they choose the option, the Form W-9 or W-8BEN will be shown with built-in validations. There is also an electronic signature pad that allows the recipient to sign electronically and submit the form.

4. Once the recipient completes and signs the form, you will be notified via webhook. The webhook payload will have the following recipient data:

   • Name, Address, and SSN/EIN for W-9
   • Name, Citizenship country, address, TIN and reduced tax rate for W-8BEN

POST WhCertificate/RequestByUrl

Request Body

Field	Type	Description
Requester	Object	Collects the Requestor identifier. TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed as the Requester.
PayerRef	String	Optional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL. Size Range: 1-50
BusinessId	Guid	Optional TaxBandits Unique Business Identifier. This ID is generated by `TaxBandits after you create a business in your account using the Business endpoint.If you do not supply the BusinessId in the request, then the URL will be generated against the default business (First business created in your account).
TIN	String	Optional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef. Size Range: 9-11 Allowed values: "EIN", "SSN" (Including hyphen)
Recipient	Object	Collects the recipient's unique identifier and other basic information of the recipient that will be pre-filled on the Form.
PayeeRef	String	An unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient in the API. Size Range: 1-50
Name	String	Optional Recipient Name. This will be pre-filled on the Form. Size Range: ..50
IsForeign	Boolean	When true, the recipient address is identified as a foreign address (Outside US). When false, the recipient address is identified as US address. Allowed values: "true", "false"
USAddress	Object	Collects US address details of the recipient.
Address1	String	Optional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. Size Range: ..35
Address2	String	Optional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..35
City	String	Optional Recipient US City. This will be pre-filled on the Form. Size Range: ..27
State	string	Optional Recipient US State Code. This will be pre-filled on the Form. Size Range: 2 Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
ZipCd	String	Optional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form. Size Range: 5-10
ForeignAddress	Object	Collects US address details of the recipient.
Address1	String	Optional Recipient’s Foreign Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. Size Range: ..35
Address2	String	Optional Recipient’s Foreign Address 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..35
City	String	Optional Recipient’s Foreign City Name. This will be pre-filled on the Form. Size Range: ..27
ProvinceOrStateNm	String	Optional Recipient’s Foreign State or Province Name. This will be pre-filled on the Form. Size Range: ..30
Country	string	Optional Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
IsTINMatching	Boolean	Optional TIN Matching will be enabled when the value is set as True. Once the recipient completes Form W-9, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify the client via the webhook with the TIN results. Allowed values: "true", "false"
Customization	Object	Collects the customizations like TIN service, Business Logo and Callback URLs.
BusinessLogoUrl	String	Optional Business Logo that will be displayed on the Form completion page. Size Range: ..150
RedirectUrls	Object	Collects the RedirectUrls like ReturnUrl and CancelUrl.
ReturnUrl	String	Optional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-9/W-8BEN. Size Range: ..150
CancelUrl	String	Optional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on the Form W-9/W-8BEN. Note: If you do not provide the Cancel Callback Redirection URL, the cancel button will not be shown to the recipient. Size Range: ..150
WebhookRef	Guid	Optional Unique identifier of the webhook. TaxBandits generates a unique Webhook Reference (GUID) 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.

Note : You need to supply one of these values - TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
PayeeRef	String	Unique identifier of the recipient.
URL	String	URL that can be embedded on the client's website using Iframe or other means.
Errors	object[]	Collection of errors for the Recipient.
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.

WHCertificate Sample Request 1: Request WhCertificate URL with the recipient Payee Reference.

{
 "Requester": null,
 "Recipient": {
   "PayeeRef": "123456",
   "IsTINMatching": true
 },
 "Customization": {
   "BusinessLogoUrl": "https://example.com"
 },
 "RedirectUrls": {
   "ReturnUrl": "https://example.com",
   "CancelUrl": "https://example.com"
 }
}

WHCertificate Sample Response 1:

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
  "PayeeRef": "Pe123451234",
  "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
  "Errors": null
}

WHCertificate Sample Request 2: Request WhCertificate URL with Payee Reference and businessId.

{
  "Requester": {
    "PayerRef": null,
    "BusinessId": "0D12C79F-5FD6-4983-9809-023F0C2BF826",
    "TIN": null
  },
  "Recipient": {
    "PayeeRef": "123456",
    "IsTINMatching": false
  },
  "Customization": null,
  "RedirectUrls": null
}

WHCertificate Sample Response 2:

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
  "PayeeRef": "Pe123451234",
  "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
  "Errors": null
}

WHCertificate Sample Request 3: Request WhCertificate URL with Payee Reference and Recipient details.

{
  "Requester": null,
  "Recipient": {
    "PayeeRef": "123456",
    "Name": "John",
    "IsForeign": true,
    "USAddress": null,
    "ForeignAddress": {
      "Address1": "1751 Kinsey Rd",
      "Address2": "Main St",
      "City": "Dothan",
      "ProvinceOrStateNm": "TN",
      "Country": "IN",
      "PostalCd": "641016"
    },
    "IsTINMatching": true
  },
  "Customization": null,
  "RedirectUrls": null
}

WHCertificate Sample Response 3:

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
  "PayeeRef": "Pe123451234",
  "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
  "Errors": null
}

WHCertificate Sample Request 4: Request WhCertificate URL with Payee Reference, Payer Reference, Business Logo, Callback redirection URLs and TIN Matching service.

{
  "Requester": {
    "PayerRef": "B12345"
  },
  "Recipient": {
    "PayeeRef": "123456",
    "Name": "John",
    "IsForeign": true,
    "USAddress": {
      "Address1": "1751 Kinsey Rd",
      "Address2": "Main St",
      "City": "Dothan",
      "State": "AL",
      "ZipCd": "36303"
    },
    "ForeignAddress": {
      "Address1": "1751 Kinsey Rd",
      "Address2": "Main St",
      "City": "Dothan",
      "ProvinceOrStateNm": "TN",
      "Country": "IN",
      "PostalCd": "641016"
    },
    "IsTINMatching": true
  },
  "Customization": {
    "BusinessLogoUrl": "https://example.com"
  },
  "RedirectUrls": {
    "ReturnUrl": "https://example.com",
    "CancelUrl": "https://example.com"
  }
}

WHCertificate Sample Response 4:

{
   "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
   "PayeeRef": "Pe123451234",
   "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
   "Errors": null
}

WHCertificate Sample Request 5: Request WhCertificate URL with WebhookRef node.

{
  "Requester": null,
  "Recipient": {
    "PayeeRef": "Pe123451234",
    "IsTINMatching": true
  },
  "Customization": {
    "BusinessLogoUrl": "https://image.com.png"
  },
  "RedirectUrls": {
    "ReturnUrl": "https://abccompany.com/Success",
    "CancelUrl": "https://abccompany.com/Failed"
  },
  "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d"
}

WHCertificate Sample Response 5:

{
   "SubmissionId": "9b7ddb71-a6ac-4312-ab09-7ad9a2b3508e",   
   "PayeeRef": "Pe123451234",
   "Url": "https://esignw9.taxforall.com?uId=88d1bedb-f6b4-4300-9186-751719050030",
   "Errors": null
}

Status

The status of a particular recipient’s W-9 or W-8BEN can be retrieved using this endpoint.

This method will return the status of all the FormWHCertificate requests (complete and incomplete) to a particular recipient.

• WHCertificate Statuses

  • URL_Generated - The WHCertificate (W-9/W-8BEN) URL is generated by TaxBandits, but the recipient has not opened it.

  • Opened - The recipient has clicked the URL, opened the page and has yet to complete it.

  • COMPLETED_AND_TIN_MATCH_INPROGRESS - Form W-9 has been completed and the TIN Matching process is inprogress. Applicable only if the recipient has completed Form W-9.

  • Completed - Recipient has completed and signed the Form W-9/W-8BEN. If TIN Matching service is opted in the request and the recipient has completed W-9, then the completed status will be returned only when the TIN Matching status is Success for the Recipient.

  • Invalid - TIN given by the recipient does not match with the IRS database and the W-9 is now invalid. You can request a new W-9 from the recipient. Applicable only if the recipient has completed Form W-9.

• TIN Statuses (Applicable only for the recipients filling Form W-9)

  • Order_Created - Recipient completed the Form W-9 and a TIN Matching order is created in Taxbandits. The TIN Matching request is yet to be sent to the IRS.

  • Under_Process - Our system has batched the TIN Requests and is queued for IRS submission.

  • Sent_to_Agency - The order has been sent to the IRS for TIN verification and TaxBandits is waiting for the response from the IRS. Usually the IRS takes one business day to complete the TIN verification process.

  • Success - Recipient’s Name and TIN combination matches with the records in the IRS database.

  • Failed - Recipient’s Name and TIN combination does not match with the records in the IRS database.

Key Points

• If there are multiple W-9s/W-8BENs for the same PayeeRef, the statuses of all the W-9s will be listed as an array.

• If you do not supply the BusinessId in the request, then the status of the W-9/W-8BEN that matches the Email or PayeeRef linked to the default business will be retrieved.

GET WhCertificate/Status

Request Body

Field	Type	Description
PayeeRef	String	A unique identifier for each recipient completing the Form W-9 and W-8BEN. Size Range: 1-50
BusinessId	Guid	Optional Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped..
TIN	String	Optional Taxpayer Identification Number. Use this as an alternative for BusinessId. Size Range: 9-11 Allowed values: "EIN", "SSN"(Including hyphen)

Response Body

Field	Type	Description
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the 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	Unique identifier of the recipient.
TotalRecords	int	Number of records available for the Payee Reference.
Status	Object[]	Statuses of the records for the recipient.
SubmissionId	Guid	Submission ID of the original Form Request.
FormType	String	Form Type. W-9 or W-8BEN.
FormStatus	String	Status of the form.
StatusTs	String	Timestamp of the Form status.
TINMatching	Object	TIN Matching information.
Status	String	TIN Matching status.
StatusTs	String	Timestamp of the TIN Status.
Errors	Object	Shows the detailed error message.
Errors	Object	Shows detailed error information of the API request.
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.

Sample Request 1: Get W-9 status of a recipient with PayeeRef and BusinessId.

WhCertificate/Status?PayeeRef=Pe123451234&BusinessId=1df66ad8-cb70-4b3f-9b9b-a216bd72814698F620

Sample Response 1:

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Sample Request 2: Get W-9 status of a recipient with Payee Reference and BusinessId. This recipient was requested to complete W-9 multiple times using the same PayeeRef.

WhCertificate/Status?PayeeRef=Pe123451234&BusinessId=1df66ad8-cb70-4b3f-9b9b-a216bd728146

Sample Response 2: Statuses of the W-9s are listed as an array.

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 3,
 "Status": [
   {
     "SubmissionId": "9107721a-5a8e-4869-8298-b6afaba9d3de",
     "FormType": null,
     "FormStatus": "URL_GENERATED",
     "StatusTs": "2021-09-29 04:23:18 -04:00",
     "TINMatching": null
   },
   {
     "SubmissionId": "68136ace-45f2-4db6-845d-3a89de821427",
     "FormType": "FormW9",
     "FormStatus": "OPENED",
     "StatusTs": "2021-09-29 04:23:15 -04:00",
     "TINMatching": null
   },
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 04:23:22 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Sample Request 3: Get W-9 status of a recipient with PayeeRef and TIN.

WhCertificate/Status?PayeeRef=Pe123451234&TIN=122222222

Sample Response 3:

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Sample Request 4: Get W-9 status of a recipient with PayeeRef and no Requester (BusinessId or TIN) information.

WhCertificate/Status?PayeeRef=Pe123451234

Sample Response 4: Since the Requester information was not given, the system will look for W-9s under the default business and return the result.

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Webhook Responses

TaxBandits now introduces adding multiple webhook Callback URLs to the same event type. Whenever a recipient completes the Form W-9 or W-8BEN, the webhook will be posted to the Callback URL the client prefers by giving its WebhookRef in the request payload. The support for multiple webhooks for the same event type could be a big help during development as well as in the production environment to act as a load balancer.

A maximum of 5 webhook Callback URLs can be added to the WhCertificate Status Change event type.

Go to Webhooks for information on Webhooks in TaxBandits.

How does it work?

1. Log in to the developer console.

   • Sandbox Console URL: sandbox.taxbandits.com (opens new window)
   • Live Console URL: console.taxbandits.com (opens new window)

2. Then navigate to Settings >> Webhooks.

3. To add the multiple webhook Callback URLs inside the console site. Click on the Add Webhook button.

4. On the Add Webhook pop-up, choose the Event Type as WhCertificate Status Change. Once you select the event type, you will have the option to add up to 5 webhook Callback URLs.

5. On Save, TaxBandits generates a unique Webhook Reference (GUID) against each Callback URL. Store these Webhook References at your end and pass them in the request JSON for us to 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 (Callback URL 1).

6. When you call the WhCertificate/RequestByUrl endpoint, you can mention the preferred Callback URL by sending the stored Webhook Reference to the node WebhookRef. The WebhookRef node is optional.

When a recipient completes the W-9/W-8BEN, the webhook will be posted to the Callback URL that is tied to the WebhookRef given in the request.

If you do not specify the WebhookRef in the request, then the webhook will be posted to the default Callback URL.

Sample request JSON with WebhookRef

Response Body

Field	Type	Description
FormType	String	Type of Form (W-9 or W-8BEN).
WebhookRef	Guid	Unique identifier of the webhook. TaxBandits generates a unique Webhook Reference (GUID) 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.
FormW9	Object	Contains Form W-9 Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the 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	Unique identifier of the recipient
RecipientId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to update.
W9Status	String	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.
Errors	String	Shows the detailed error message.
FormW9RequestType	String	Form W-9 requested Type. COMMON_URL_API - Form W-9 was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-9
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 API method RequestByURL
FormData	Object	Form W-9 data 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. Either EIN or SSN
TIN	string	Recipient’s TIN
Address	Object	Recipient’s complete address
Address1	string	Recipient’s Address 1 (number, street)
Address2	string	Recipient’s Address 2 (apt. or suite no.)
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 the recipient is 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	Shows detailed error information.
FormW8Ben	Object	Form W-8BEN Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Business Name of the requester. 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	Unique identifier of the recipient
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status.
FormW8BENRequestType	String	Form W-8BEN requested Type. COMMON_URL_API - Form W-8BEN was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-8BEN.
Email	String	Email Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL.
FormData	Object	Form W-8BEN data of the recipient.
NmOfIndividual	string	Name of the Foreign Individual.
CitizenOfCountry	string	Recipient country of citizenship.
USTINType	string	TIN type of the recipient. Either SSN or ITIN.
USTIN	string	Recipient’s TIN
ForeignTIN	string	Foreign TIN of the recipient.
DOB	string	Date of Birth of the recipient
PermanentAddress	Object	Recipient’s permanent address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
MailingAddress	Object	Recipient’s mailing address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
TaxTreatyBenefits	Object	Tax Treaty Benefits.
BeneficiaryCountry	string	Country where the recipient claim to be a resident for income tax treaty purposes.
ClaimingProvArticlePara	string	Article and paragraph of the treaty benefits.
RateOfWH	string	Rate of Withholding.
TypeOfIncome	string	Type of income for which recipient claiming the treaty benefits.
AdditionalConditions	string	Additional conditions from the tax treaty benefits.
Signature	Object	Signature of the recipient.
SignerNm	string	Name of the signer.
CapacityInWhichActing	string	If the form is signed by an agent on the individual’s behalf, enter the capacity in which they are acting.
Errors	Object	Shows detailed error information. Sample Webhook Response for W8Ben :

Scenario 1: The recipient has completed Form W-8BEN.

{
 "FormType": "W8Ben",
 "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "FormW9": null,
 "FormW8Ben": {
   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
   "Requester": {
     "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
     "PayerRef": null,
     "BusinessNm": "John Enterprises",
     "TINType": "EIN",
     "TIN": "22-2222222"
   },
   "PayeeRef": "7484391234545",
   "W8BENStatus": "COMPLETED",
   "StatusTs": "2021-02-19 14:36:28 -05:00",
   "FormW8BENRequestType": "URL_API",
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "steve@abcinc.com",
   "FormData": {
     "NmOfIndividual": "Joseph Smith",
     "CitizenOfCountry": "Canada",
     "USTINType": "SSN",
     "USTIN": "111-11-1111",
     "ForeignTIN": null,
     "DOB": "07/08/1990",
     "PermanentAddress": {
       "Address": "123 E. Main St",
       "City": "Rock Hill",
       "State": "SC",
       "Country": "USA",
       "ZipCd": "29730"
     },
     "MailingAddress": {
       "Address": null,
       "City": null,
       "State": null,
       "Country": null,
       "ZipCd": null
     },
     "TaxTreatyBenefits": {
       "BeneficiaryCountry": "Canada",
       "ClaimingProvArticlePara": "VII",
       "RateOfWH": "27.50",
       "TypeOfIncome": "Royalties",
       "AdditionalConditions": null
     },
     "Signature": {
       "SignerNm": "Joseph",
       "CapacityInWhichActing": "Guardian"
     }
   },
   "Errors": null
 },
 "Errors": null
}

Scenario 2: The recipient has completed Form W-9 and TIN Matching is Inprogress.

{
 "FormType": "FormW9",
 "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "FormW9": {
   "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
   "Requester": {
     "BusinessId": "fb6ddd28-ad30-4fc2-bd17-38a937f2aa81",
     "PayerRef": null,
     "BusinessNm": "John Enterprises",
     "TINType": "EIN",
     "TIN": "XX-XXX2222"
   },
   "PayeeRef": "Pe123451234",
   "RecipientId": "sdf3ccee-10d8-4eb4-ab81-234234c9636",
   "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
   "StatusTs": "2021-06-24 10:40:21 -04:00",
   "TINMatching": {
     "Status": "ORDER_CREATED",
     "StatusTs": "2021-06-24 10:40:21 -04:00",
     "StatusMsg": null,
     "Errors": null
   },
   "FormW9RequestType": "Email_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": "XX-XXX1111",
     "Address": {
       "Address1": "123 E. Main St",
       "Address2": "Suite 400",
       "City": "Rock Hill",
       "State": "SC",
       "ZipCd": "29730"
     },
     "FederalTaxClassification": "C Corporation",
     "ExemptPayeeCd": "5",
     "ExemptFromFATCA": "F",
     "IsBackUpWH": false
   },
   "Errors": null
 },
 "FormW8Ben": null,
 "Errors": null
}