RequestByEmail
This endpoint sends a unique url to the recipients by email to complete their form W-9, W-8BEN or W-8BEN-E. The endpoint needs the name and the recipient’s email address to generate the unique url. The recipients will receive an email with the link to complete their forms in a secured portal. Once the recipients complete the form, you will receive a webhook notification.
How does this work?
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 the OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.
The second step is to call the [POST] WhCertificate/RequestByEmail endpoint with the following values:
- Access Token in the header as Bearer Token (generated using TaxBandits OAuth authentication API).
- Requester (BusinessId or TIN) Optional - To identify and save the W-9/W-8BEN/W-8BEN-E 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).
- 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.
- Recipient Name and Email - The recipient information like Name and Email is mandatory.
TaxBandits will send the request emails to the recipients. The email will have the link to complete either Form W-9, W-8BEN or W-8BEN-E. The recipient will complete and sign the form through a secure portal. The secured portal can be customized with the client's URL, logo and theme. 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, the client will be notified via Webhook. Multiple webhooks can be added to get notified when recipients complete their forms.
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.
- Form W-8BEN-E - Name, Country, entity, TIN, Tax benefits, etc.
Refer to Form WhCertificate webhook to learn on how to set up the webhook URLs and for a sample payload.
POST WhCertificate/RequestByEmail
Request Body
Field | Type | Description |
---|---|---|
Requester | Object | Collects the Requester 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 |
String | Email Address of the recipient. This is the email address to which the WhCertificate request email will be sent .Size Range: 1-100 | |
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" |
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. |
Response Body
Field | Type | Description |
---|---|---|
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. |
PayerRef | Guid | Unique identifier of the payer. |
TINType | String | TIN Type of the Requester. |
TIN | String | Taxpayer Identification Number of the requester. |
WhCertificate | Object | Details of Withholding Certificate requests given in the request. |
SuccessRecords | Object | Recipients with no error in the request |
PayeeRef | String | 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 | An unique identifier of a recipient. |
String | 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 in the request. Some of the errors listed under this object are, You should have at-least one business in your account to request WhCertificate Insufficient credits in the account |
Request JSON
Send WhCertificate email requests to recipients by giving the BusinessId (Requester) and recipients information like Name and Email. Make sure the Form WhCertificate Status Change webhook is configured and provide the Webhook Ref Id in the request.
{
"SubmissionManifest": {
"IsTINMatching": true
},
"Requester": {
"BusinessId": "9e284b90-aa98-4287-8e9a-38cc590a90d3",
"PayerRef":null,
"TIN": "092-11-5116"
},
"Recipients": [
{
"PayeeRef": "T@122",
"Name": "Jordan Henry",
"Email": "jordan.henry@yahoo.com"
},
{
"PayeeRef": "mia@345",
"Name": "Mia Harper",
"Email": "mia.harper@hotmail.com"
}
],
"WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667"
}
Response JSON
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": "Brian LLC",
"PayerRef": "Pe12rtgr3",
"TINType": "SSN",
"TIN": "092-11-5116"
},
"WhCertificate": {
"SuccessRecords": [
{
"PayeeRef": "T@122",
"Email": "jordan.henry@yahoo.com"
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2022-06-14 07:05:18 +05:30"
},
{
"PayeeRef": "mia@345",
"Email": "mia.harper@hotmail.com"
"WhCertificateStatus": "ORDER_CREATED",
"StatusTs": "2022-06-14 07:05:18 +05:30"
}
],
5 "ErrorRecords": null
},
"Errors": null
}