RequestByEmail
RequestByEmail
This is a payer-initiated method where you can use our API to send an email request containing a unique secure URL to each payee (recipient) for completing W-9/W-8 Forms.
How it works
1. OAuth 2.0 Authentication
As with any TaxBandits API call, begin by authenticating through the OAuth 2.0 flow to obtain an access token. This token must be included in the request header as a Bearer token. Refer to the OAuth 2.0 Authentication guide for details on JWT authentication and token handling.
2. Create Business
Before initiating a W-9/W-8 request, ensure at least one business (payer) has been created using the Business endpoint. This is a mandatory step.
3. Call the [POST] WhCertificate/RequestByEmail Endpoint
Your request must include the following:
- Authorization Header - Include the Bearer token obtained from OAuth.
- Payee Email Address - The form completion secure URL will be sent here.
- Payee Reference (Optional) - A unique ID for referencing the payee in future API calls.
- Payee Name and Address (Optional) - If included, this info will be pre-filled in the form.
- Business Identifier (Optional) - Provide the BusinessId or TIN to identify the payer associated with the request. If omitted, the form will be tied to the first business in your account.
- DBA Reference (Optional) - Used to display a specific DBA name as the requester on the form.
- Customizations (Optional) - You may include branding customization in the request, such as logo, theme colors, etc, and the redirection URLs where you want the payee to be redirected once they submit the form. You may also include a CustomizationId if you’ve generated one. Learn more
4. Payee completes the form
TaxBandits will send an email with a secure URL to the payee. Upon clicking the secure URL, the payee will be provided with the option to choose the Form W-9, W-8BEN, W-8BEN-E, or W-8BECI based on their citizenship and resident status. They can complete, e-sign, and submit the form.
5. Get notified
- Webhooks - If you’ve configured Webhooks for the event type 'WhCertificate Status Change Webhook', you will receive a webhook notification once the payee submits the form. The Webhook payload includes payee details (name, TIN, address) and a link to download the completed form. Learn more
- Status endpoint - Alternatively, you can also use the Status endpoint to retrieve the status.
- Web messaging - Instead of Webhooks, you can choose to receive notifications via web messaging. For more information, click here.
info Automate TIN Matching
If you want to validate the TINs automatically once collected, you can set the IsTINMatching as TRUE in your request JSON.
POST WhCertificate/RequestByEmail
Request Body
Field | Type | Description |
---|---|---|
SubmissionManifest | Object[] | SubmissionManifest provides brief information about submission and the services opted for. |
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. |
Requester | Object | Collects the Requester identifier TIN or TBS Business ID or PayerRef. If neither is provided, the default Business will be assumed as the Requester. |
PayerRef | String | Optional A unique payer identifier assigned by you 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 provide the BusinessId in the request, then the URL will be generated against the default business, i.e., the 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) |
DBAId | String | OptionalUnique Identifier for the DBA. |
DBARef | String | OptionalA Unique identifier for each DBA. This identifier can be used in future references for the DBA in the API. Size Range: 1 - 50 |
Recipient | Object[] | Collects the recipient's unique identifier and other basic information that will be pre-filled on the Form. |
PayeeRef | String | OptionalA unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient. Size Range: 1-50 |
Name | String | Optional Recipient Name. This will be pre-filled on the Form. Size Range: ..50 |
String | Email address of the recipient. This is the email address to which the WhCertificate request email will be sent. Size Range: 1-100 | |
Address | Object | OptionalCollects 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: ..46 |
Address2 | string | Optional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..46 |
City | string | Optional Recipient US City. This will be pre-filled on the Form. Size Range: ..46 |
State | string | Optional OptionalRecipient 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 |
WebhookRef | Guid | Optional A unique identifier of the Webhooks that TaxBandits generates against each Callback URL when adding it to 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. |
CustomizationId | Guid | Optional A unique customization identifier generated by TaxBandits after you complete the customization process in the Developer console or the unique ID you received in the response of the PortalCustomization CREATE Endpoint. endpoint. Note: You can customize the W-9/W-8 page (secure URL) with your own logo, favicon, and primary and secondary colors. |
EmailCustomizationId | Guid | Optional A unique customization identifier generated by TaxBandits after you complete the customization process in the developer console. Note: You can customize the W-9/W-8 request email template with your own logo, favicon, and primary and secondary colors. |
Customization | Object | Optional Collects the customizations like TIN service, Business Logo and Callback URLs. |
BusinessLogoUrl | String | Optional Gets the Business Logo. If given the business logo will be shown in the Iframe page. Size Range: ..150 |
LogoPosition | String | Optional Optional The position where your business logo will be placed on the page.Allowed values"LEFT", "CENTER", "RIGHT" |
InterviewFlow | Boolean | Optional As an alternative to direct-form entry, provide your recipients with an interview-style W-9/W-8 completion. |
PrimaryColor | String | Optional The color theme of the iframe page will be customized with this primary color. |
SecondaryColor | String | Optional The color theme of the iframe page will be customized with this secondary color. |
Response Body
Field | Type | Description |
---|---|---|
SubmissionId | Guid | A 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 |
FirstNm | String | First Name of the Individual Size Range: ..20 |
MiddleNm | String | Middle Name of the Individual Size Range: ..20 |
LastNm | String | Last Name of the Individual Size Range: ..20 |
Suffix | String | Suffix of the Individual Allowed values"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII" |
PayerRef | Guid | A Unique identifier of the payer. |
TINType | String | TIN Type of the Requester. |
TIN | String | Taxpayer Identification Number of the requester. |
DBAId | String | Unique Identifier for the DBA. |
DBARef | String | Unique identifier for each DBA. This identifier can be used in future references of the DBA in the API |
WhCertificate | Object | Details of Withholding Certificate requests given in the request body. |
SuccessRecords | Object | Recipients with no error in the request |
PayeeRef | String | A Unique identifier of the recipient. |
String | Email Address of the recipient to which W-9 request was sent. | |
WhCertificate Status | String | Status of the WhCertificate |
StatusTs | String | Timestamp of the WhCertificate status |
ErrorRecords | Object | Details of the recipients with errors |
PayeeRef | String | A Unique identifier of the recipient. |
String | The email address of the recipient given in the request | |
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. |
Errors | object[] | Collection of errors for the submissions. 'You should have at least one business in your account to request WhCertificate’ 2.‘Insufficient credits in the account’ |
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. |
Request JSON
- Sample 1
- Sample 2
- Sample 3
Send an email to the recipient's provided email address with a secure URL to complete the W-9/W-8 form. Automatically link the completed form to the business corresponding to the BusinessId provided. When the recipient submits the form, trigger the 'WhCertificate Status Change webhook' to send a payload containing the submitted form data.
{
"SubmissionManifest": {
"IsTINMatching": true
},
"Requester": {
"BusinessId": "9e284b90-aa98-4287-8e9a-38cc590a90d3",
"PayerRef":null,
"TIN": "092-11-5116"
},
"Recipients": [
{
"PayeeRef": "T@122",
"Name": "Jordan Henry",
"Email": "mark@sample.com"
},
{
"PayeeRef": "mia@345",
"Name": "Mia Harper",
"Email": "mark@sample.com"
}
],
"WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667"
}
RequestByEmail with DBA details
{
"SubmissionManifest": {
"IsTINMatching": false
},
"Requester": {
"BusinessId": null,
"PayerRef": null,
"TIN": null,
"DBAId": "dfb13337-f49b-42fb-b989-07c674a7b81c",
"DBARef": "#001"
},
"Recipients": [
{
"PayeeRef": "1452631",
"Name": "Mark Davis",
"Email": "mark@sample.com"
}
]
}
RequestByEmail with Portal customization Id and Email customization Id
{
"SubmissionManifest": {
"IsTINMatching": true
},
"Requester": {
"BusinessId": "959763e4-26d3-4d52-a8eb-b954b22616fd",
"PayerRef": "Pay025",
"TIN": "865923062",
"DBAId": null,
"DBARef": null
},
"Recipients": [
{
"PayeeRef": "payeeref016",
"Name": "Shawn Williams",
"Email": "shawn@sample.com"
}
],
"WebhookRef": null,
"CustomizationId": "D6ACC1C4-74E5-4A60-B569-77F4612BD988",
"EmailCustomizationId": "2FF35B72-2EEF-466F-90EB-505FD250FD1L",
"Customization": {
"InterviewFlow": true,
"BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
"LogoPosition": "CENTER",
"PrimaryColor": "#1321E6",
"SecondaryColor": "#0F700C"
}
}
Response JSON
- Response 1
- Response 2
- Response 3
An email with the link for WhCertificate will be sent to the provided recipient email address. Since the business id is provided, the completed form will save against the same. When a recipient submits the form, the Form WhCertificate Status Change webhook payload will include the form data.
{
"SubmissionId": "2d1797a2-5e56-4da4-a59d-e82e858ffbd8",
"Requester": {
"BusinessId": "9e284b90-aa98-4287-8e9a-38cc590a90d3",
"BusinessNm": "Snowdaze LLC",
"PayerRef": "Pe12rtgr3",
"TINType": "SSN",
"TIN": "092-11-5116"
},
"WhCertificate": {
"SuccessRecords": [
{
"PayeeRef": "T@122",
"Email": "mark@sample.com",
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2022-06-14 07:05:18 +05:30"
},
{
"PayeeRef": "mia@345",
"Email": "mark@sample.com",
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2022-06-14 07:05:18 +05:30"
}
],
"ErrorRecords": null
},
"Errors": null
}
An email with the link for WhCertificate will be sent to the provided recipient email address. Since the DBA details is provided, the completed form will be saved against the Business ID associated with the given DBA ID. When a recipient submits the form, the Form WhCertificate Status Change webhook payload will include the form data.
{
"SubmissionId": "09bddc72-5111-414a-ad6c-923140452e2e",
"Requester": {
"BusinessId": "2f7db6c1-c7aa-4dd0-8ae3-e45e4c5db106",
"BusinessNm": "Snowdaze LLC",
"PayerRef": "96459",
"TINType": "SSN",
"TIN": "644-51-5744",
"DBAId": "dfb13337-f49b-42fb-b989-07c674a7b81c",
"DBARef": "#001"
},
"WhCertificate": {
"SuccessRecords": [
{
"PayeeRef": "1452631",
"Email": "mark@sample.com",
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2024-04-03 08:38:09 -04:00"
}
],
"ErrorRecords": null
},
"Errors": null
}
An email with the link for WhCertificate will be sent to the provided recipient email address. Since the Business ID is provided, the completed form will be saved against the same. When a recipient submits the form, the Form WhCertificate Status Change webhook payload will include the form data.
{
"SubmissionId": "d57512a3-775d-4395-ad84-4d262e2d8aeb",
"Requester": {
"BusinessId": "959763e4-26d3-4d52-a8eb-b954b22616fd",
"BusinessNm": "Snowdaze LLC",
"FirstNm": null,
"MiddleNm": null,
"LastNm": null,
"Suffix": null,
"PayerRef": "Pay025",
"TINType": "EIN",
"TIN": "86-5923062",
"DBAId": null,
"DBARef": null
},
"WhCertificate": {
"SuccessRecords": [
{
"PayeeRef": "payeeref016",
"Email": "shawn@sample.com",
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2024-09-18 01:50:38 -04:00"
}
],
"ErrorRecords": null
},
"Errors": null
}