Version: 1.7.3

RequestByUrl

Allows recipients to choose either Form W-9 or Form W-8BEN, fill, e-sign, and submit information through a browser URL. Response returns an unique URL that may be opened on its own or embedded within an Iframe into a web page or native app. Send in a request with a unique Payee Reference along with a business identifier (Business Id or TIN).

Recommended when you have a portal for your vendors, where you can place a link to collect the W9 or W8BEN information. Option to customize logo and the callback redirection URLs are available.

How does this work?

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. 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). Can be the Vendor id, contractor number, recipient email address, or a random number. Will be used to identify the recipient for future references.
- PayerRef, Business Id (Business Identifier) or TIN - 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. If you don’t supply one in the request, it will be associated with the default business (first business created in your account).
- Recipient Name and Address (optional) - When passed in the request, will be pre-filled on the form the recipient fills.
- Business Logo and Callback URLs (optional) - Customize the business logo on the Form W-9/Form W8-BEN. Set callback redirection URLs upon submission or cancellation.
- WebhookRef (optional) - Pass the Webhook Reference ID and we will post the Webhook response to the corresponding Callback URL. If you do not specify one, the Webhook will be posted to the default Webhook URL.
- TaxBandits API 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 and resident status. Accordingly, Form W-9 or W-8BEN will be shown with built-in validations. An electronic signature pad that allows the recipient to sign electronically and submit the form is available.
Once the recipient completes and signs the form, you will be notified via webhook. If the node WebhookRef in the request JSON has a Webhook Reference ID, the Webhook response will be posted to the corresponding Callback URL.

The webhook payload will have the following recipient data:

For W-9 - Name, address, email, TIN Matching status, form data, PDFURL to download completed form, etc.
For W-8BEN - Name, Citizenship country, address, and reduced tax rate.

Refer to Form WhCertificate webhook to learn on how to set up the webhook URLs and for a sample payload.

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,9
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 Request 1: Request URL for form W-9 with Payee Reference and opt for TIN Matching. URLs are supplied for business logo customization as well as success and cancel request.

{
 "Requester": null,
 "Recipient": {
   "PayeeRef": "123456",
   "IsTINMatching": true
},
 "Customization": 
{
   "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png"
},
 "RedirectUrls": 
{
   "ReturnUrl": "https://example.com",
   "CancelUrl": "https://example.com"
}
}

WHCertificate Response 1: Unique URL with built-in validations for recipients to complete Form W-9/Form W-8BEN through a browser URL. Since the Requester is not specified, the recipient will be associated with the default business. Business logo and redirection URLs will be rendered.

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
  "PayeeRef": "Pe123451234",
  "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
  "Errors": null
}

WHCertificate Request 2: Request URL with Business ID and Payee Reference. Not opting for W-9 TIN Matching, or customization.

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

WHCertificate Response 2: A unique URL with built-in validations for recipients to complete Form W-9/Form W-8BEN through a browser URL. Recipients will be associated with the Business ID.

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
  "PayeeRef": "Pe123451234",
  "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
  "Errors": null
}

WHCertificate Request 3: Request URL with Payee Reference and Recipient details. Opt for W-9 TIN Matching. No Requester details sent in. Not opting for any customization.

{
  "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 Response 3: A unique URL with Recipient details pre-filled on the form. With the Requester object being null, the recipient will be associated with the default business.

{
  "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
  "PayeeRef": "Pe123451234",
  "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
  "Errors": null
}

WHCertificate 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://www.spanenterprises.com/Content/Images/span.png"
  },
  "RedirectUrls": {
    "ReturnUrl": "https://example.com",
    "CancelUrl": "https://example.com"
  }
}

WHCertificate Response 4: Request URL with Payer Reference, Payee Reference, Payer details, W-9 TIN Matching, and customization.

{
   "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
   "PayeeRef": "Pe123451234",
   "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
   "Errors": null
}

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

{
  "Requester": null,
  "Recipient": {
    "PayeeRef": "Pe123451234",
    "IsTINMatching": true
  }},
  "Customization": {
    "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png"
  }},
  "RedirectUrls": {
    "ReturnUrl": "https://example.com",
    "CancelUrl": "https://example.com"
  }},
  "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d"
}

WHCertificate Response 5: Unique URL with Recipient details pre-filled on the form. Will be associated with the business linked to Payee Reference. Business logo and redirection URLs will be rendered.

{
   "SubmissionId": "9b7ddb71-a6ac-4312-ab09-7ad9a2b3508e",   
   "PayeeRef": "Pe123451234",
   "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
   "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration