Skip to main content
Version: 1.7.0

RequestByEmail

This endpoint sends a unique url via email to the recipients to complete their form W-9. 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 W-9 in a secured portal. Once the recipients complete the Form W-9, you will receive a webhook notification for the W-9 data.

How does it 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 integrating with subsequent requests.

  2. The second step is to call the [POST] FormW8Ben/RequestByEmail endpoint with the following values:

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API).
    • Payee Reference (Unique information that identifies the Recipient. Optional) - A unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient in the API.
    • Recipient Name and Address (Optional) - The recipient information will be pre-filled on the form when passed in the request.
    • Business Logo and Callback URLs (Optional) - Customize the business logo on the Form Form W-9. Set callback redirection URLs upon submission or cancellation. 
  3. Requester (BusinessId or TIN(optional) value to save the W9 under a particular Business) - To identify and save the W-9 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).

  4. TaxBandits will send the W-9 request emails to the recipients. The email will have the link to complete the Form W-9.

  5. The recipient will complete and sign Form W-9 in a secured portal. The secured portal can be whitelabeled with the client's URL, logo and theme.

  6. Once the recipient completes and signs the Form W-9, the client will be notified via Webhook. The Webhook payload will have the W-9 data such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9.

Refer to Form W-9 webhook to learn more about webhook set up and sample payload.

  1. If IsTINMatching is set as ‘TRUE’, TaxBandits will validate the recipient TIN against the IRS database.
POST FormW9/RequestByEmail

Request Body

FieldTypeDescription
SubmissionManifestobjectSubmissionManifest provides brief information about submission and the services opted.
    IsTINMatchingBooleanTIN Matching service will be enabled when the value is set as True. Once the recipient signs the Form W-9, TaxBandits will validate the recipient’s Name, TIN and TINType with the IRS.
RequesterobjectBusiness you want the W-9s to be created under. If you do not supply the requester information, then the W-9s will be created against the default business (First business created in your account)
    BusinessIdGuidOptional Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
    TINStringOptional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN
Size Range: 9-11
Recipientsobject[]Collection of Recipient's Name and Email
    PayeeRefStringOptional 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
    NamestringName of the recipient
Size Range: 1-80
    EmailstringEmail Address of the recipient. This is the email address to which the W-9 request email will be sent.
Size Range: 1-50

Response Body

FieldTypeDescription
SubmissionIdGuidUnique 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.
    TINTypeStringTIN Type of the Requester.
    TINStringTaxpayer Identification Number of the requester.
FormW9RecordsObjectDetails of Form W-9 requests given in the request.
    SuccessRecordsObjectRecipients with no error in the request
        PayeeRefStringUnique identifier of the recipient.
        EmailStringEmail Address of the recipient to which W-9 request was sent.
        W9StatusStringStatus of the W-9
        StatusTsStringTimestamp of the W-9 status
    ErrorRecordsObjectDetails of the recipients with errors
        PayeeRefStringAn unique identifier of a recipient.
        EmailStringEmail 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 in the request. Some of the errors listed under this object are, You should have at-least one business in your account to request W-9 Insufficient credits in the account

Request 1: Pass BusinessId and recipient’s name and email address. W-9 email requests will be triggered to recipients. Make sure the Form W-9 Status Change webhook is configured.

{ "SubmissionManifest": {   "IsTINMatching": true }, "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "TIN": null }, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 1: W-9 requests to multiple recipients happen in a single submission and all W-9s in this submission are linked to the same BusinessId. When a recipient submits the FORM W-9, the Form W-9 Status Change webhook payload will include the W-9 data.

{ "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d", "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "BusinessNm": "John Enterprises",   "TINType": "EIN",   "TIN": "22-2222222" }, "FormW9Records": {   "SuccessRecords": [     {      "PayeeRef": "8987844654654654",       "Email": "allen.smith@abc.com",       "W9Status": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}

Request 2: Pass Business TIN instead of BusinessId along with recipient information. TIN must be associated with a business in the account.

{ "SubmissionManifest": {   "IsTINMatching": true }, "Requester": {   "BusinessId": null,   "TIN": "22-2222222" }, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 2: All W-9s in this submission are linked to the same Business TIN. On W-9 submission, the Form W-9 Status Change webhook payload will include the W-9 data.

{ "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d", "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "BusinessNm": "John Enterprises",   "TINType": "EIN",   "TIN": "22-2222222" }, "FormW9Records": {   "SuccessRecords": [     {      "PayeeRef": "8987844654654654",       "Email": "allen.smith@abc.com",       "W9Status": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}

Request 3: Pass just the recipient information without the Business (Requestor) details and request TIN Matching on the W-9 submissions. The recipients will be tied to the default business.

{ "SubmissionManifest": {   "IsTINMatching": true }, "Requester": null, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 3: All W-9s in this submission are linked to the default Business. Requestor information of default business is returned along with order details. On W-9 submission, the Form W-9 Status Change webhook payload will include W9 and TIN Matching statuses.

{ "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d", "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "BusinessNm": "William Enterprises",   "TINType": "EIN",   "TIN": "11-1111111" }, "FormW9Records": {   "SuccessRecords": [     {      "PayeeRef": "8987844654654654",       "Email": "allen.smith@abc.com",       "W9Status": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}

Request 4: Pass the W-9 request with an invalid email address format.

{ "SubmissionManifest": {   "IsTINMatching": true }, "Requester": {   "BusinessId": null,   "TIN": "22-2222222" }, "Recipients": [   {     "PayeeRef": "8987844654654658",     "Name": "Allen Smith",     "Email": "allen.smith@abccom"   } ]}

Response 4: The order is not created and the invalid email format error is returned in the ErrorRecords tag.

{ "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d", "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "BusinessNm": "John Enterprises",   "TINType": "EIN",   "TIN": "22-2222222" }, "FormW9Records": {       "SuccessRecords": null,       "ErrorRecords": [           {               "PayeeRef": "8987844654654658",               "Email": "allen.smith@abccom",               "Errors": [                   {                       "Id": "F08-100022",                       "Name": "Email",                       "Message": "Invalid Email address."                   }               ]           }       ]   }, "Errors": null}

Your IRS-Authorized E-filing Experts for
Form 1099, W-2, W-9, 1095, 94x, & more