Skip to main content
Version: 1.7.3

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 notification to get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. Refer to the OAuth 2.0 Authentication for more information on JWT authentication and integrating with 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).
    • Payee Email Address - The link to complete W-9 / W-8BEN / W-8BEN E will be sent to this email address.
    • Payee Reference (Optional) - A unique identifier for each payee who completes Form W-9. This identifier will be used in future references of the payee in the API.
    • Payee Name and Address (Optional) - The payee information will be pre-filled on the form when passed in the request.
    • Requester (Business ID or TIN) (optional) - To identify and save the W-9/W-8 under a particular business. Refer to the Business endpoint to learn more about creating a business in TaxBandits. If you don’t provide a Business ID or TIN in the request, the W-9/W-8 will be associated with the default business, i.e., the first business created in your account.
    • DBA Reference (Optional) - If you have multiple DBA names for your business, you can provide the DBA name you want to use as the Requester Name on W-9/W-8 forms.

  4. TaxBandits will send the W-9/W-8 request emails to the payees. The email will have the link to complete Form W-9 / W-8BEN / W-8BEN E.

  5. The payees will complete and e-sign the form in a secure portal. The secured portal can be white-labeled with your URL, logo, and theme.

  6. Once the payee completes and signs the form, you will be notified via Webhook. The Webhook payload will have the form information, such as the name, address, EIN/SSN, etc., along with the link to download the completed form.

    Refer to Form WhCertificate webhook to learn more about webhook setup and sample payload.

  7. If IsTINMatching is set to ‘TRUE’, TaxBandits will validate the payee’s TIN against the IRS database.

POST WhCertificate/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestObject[]SubmissionManifest provides brief information about submission and the services opted for.
IsTINMatchingBooleanIf set as True, TIN Matching service will be enabled. Once the recipient signs the Form W-9, TaxBandits will validate the recipient’s Name, TIN, and TINType with the IRS.
RequesterObjectCollects the Requester identifier TIN or TBS Business ID or PayerRef. If neither is provided, the default Business will be assumed as the Requester.
    PayerRefStringOptional A unique payer identifier assigned by you while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
    BusinessIdGuidOptional 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.
    TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11.
DBAIdStringOptionalUnique Identifier for the DBA.
DBARefStringOptionalA Unique identifier for each DBA. This identifier can be used in future references for the DBA in the API.
Size Range: 1 - 50
RecipientObject[]Collects the recipient's unique identifier and other basic information that will be pre-filled on the Form.
    PayeeRefStringA 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
    NameStringOptional Recipient Name. This will be pre-filled on the Form.
Size Range: ..50
    EmailStringEmail address of the recipient. This is the email address to which the WhCertificate request email will be sent.
Size Range: 1-100
    AddressObjectOptionalCollects Foreign address details of the recipient.
    Address1StringOptionalRecipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..35
    Address2StringOptionalRecipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..35
    CityStringOptionalRecipient US City. This will be pre-filled on the Form.
Size Range: ..27
    StateStringRecipient US State Code. This will be pre-filled on the Form.
Size Range: 5..10
    ZipCdStringOptionalRecipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
    WebhookRefGuidOptional 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": "mark@sample.com"
   },
    {
     "PayeeRef": "mia@345",
     "Name": "Mia Harper",
     "Email": "mark@sample.com"
   }
 ],
"WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667"
}

Response Body

FieldTypeDescription
SubmissionIdGuidA Unique identifier of a submission.
RequesterObjectRequester information.
    BusinessIdGuidA unique identifier of the business.
    BusinessNmStringRequester 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
    PayerRefGuidA Unique identifier of the payer.
    TINTypeStringTIN Type of the Requester.
    TINStringTaxpayer Identification Number of the requester.
    DBAIdStringUnique Identifier for the DBA.
    DBARefStringUnique identifier for each DBA. This identifier can be used in future references of the DBA in the API
WhCertificateObjectDetails of Withholding Certificate requests given in the request body.
    SuccessRecordsObjectRecipients with no error in the request
        PayeeRefStringA Unique identifier of the recipient.
        EmailStringEmail Address of the recipient to which W-9 request was sent.
        WhCertificate StatusStringStatus of the WhCertificate
        StatusTsStringTimestamp of the WhCertificate status
    ErrorRecordsObjectDetails of the recipients with errors
        PayeeRefStringA Unique identifier of the recipient.
        EmailStringThe email address of the recipient given in the request
        Errorsobject[]Collection of errors for the recipient
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows the error message.
Errorsobject[]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’
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows 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": "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
}