RequestByEmail

This is a payer-initiated method wherein our API endpoint will be used to send an email request containing a unique URL to the payees (recipients) for the completion of W-9, W-8BEN, or W-8BEN-E Forms.

In order to generate this unique url, the recipient’s name and email address are required. Once they complete the Form W-9 using this url, you will receive a notification through Webhook regarding the W-9 completion.

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 the OAuth 2.0 Authentication for more information on JWT authentication and how to integrate it with the subsequent requests.

2. Create a Business in TaxBandits. It's mandatory that you have added at least one business before requesting this endpoint.

3. The next 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 - A unique identifier of the payee (recipient), such as vendor ID, contractor number, recipient email address, or a random number. This will be used for the future references of the recipient.
   • Recipient Name and Email - The recipient information, such as Name and Email, is mandatory.

4. 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.

5. The recipient will complete and e-sign the Form through a secure portal. This secured portal can be customized with your Business URL, logo, and theme.

6. Once the recipient completes and e-signs the form, you will be notified via Webhooks. 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 the completed form, etc.
• For W-8BEN - Name, country, address, and reduced tax rate.
• Form W-8BEN-E - Name, country, entity, TIN, Tax benefits, etc.

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

POST WhCertificate/RequestByEmail 

Request Body

Field	Type	Description
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 A unique business identifier generated by TaxBandits after you create a business in your account using the Business endpoint. If you do not provide a BusinessId in the request, 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.
Recipient	Object	Collects the recipient's unique identifier and other basic information that will be pre-filled on the Form.
PayeeRef	String	A 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
Email	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/W-8, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify you via Webhooks. Allowed values: "true", "false"
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.

Request 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 be saved against the same. When a recipient submits the form, the Form WhCertificate Status Change Webhook payload will include the 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": "sample@bodeem.com"
   },
    {
     "PayeeRef": "mia@345",
     "Name": "Mia Harper",
     "Email": "sample@bodeem.com"
   }
 ],
"WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667"
}

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
PayerRef	Guid	A 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 body.
SuccessRecords	Object	Recipients with no error in the request
PayeeRef	String	A Unique identifier of the recipient.
Email	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.
Email	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.

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": "Snowdaze LLC",
        "PayerRef": "Pe12rtgr3",
        "TINType": "SSN",
        "TIN": "092-11-5116"
    },
    "WhCertificate": {
        "SuccessRecords": [
            {
                "PayeeRef": "T@122",
                "Email": "sample@bodeem.com",
                "WhCertificateStatus": "ORDER_CREATED",
                "StatusTs": "2022-06-14 07:05:18 +05:30"
            },
            {
                "PayeeRef": "mia@345",
                "Email": "sample@bodeem.com",
                "WhCertificateStatus": "ORDER_CREATED",
                "StatusTs": "2022-06-14 07:05:18 +05:30"
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}