Version: 1.7.1

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?

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.
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.
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).
TaxBandits will send the W-9 request emails to the recipients. The email will have the link to complete the Form W-9.
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.
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.

If IsTINMatching is set as ‘TRUE’, TaxBandits will validate the recipient TIN against the IRS database.

POST FormW9/RequestByEmail

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides brief information about submission and the services opted.
IsTINMatching	Boolean	TIN 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.
Requester	object	Business 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)
BusinessId	Guid	`Optional` Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
TIN	String	`Optional` Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN Size Range: 9-11
Recipients	object[]	Collection of Recipient's Name and Email
PayeeRef	String	`Optional` 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	Name of the recipient Size Range: 1-80
Email	string	Email 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

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.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
FormW9Records	Object	Details of Form W-9 requests given in the request.
SuccessRecords	Object	Recipients with no error in the request
PayeeRef	String	Unique identifier of the recipient.
Email	String	Email Address of the recipient to which W-9 request was sent.
W9Status	String	Status of the W-9
StatusTs	String	Timestamp of the W-9 status
ErrorRecords	Object	Details of the recipients with errors
PayeeRef	String	An unique identifier of a recipient.
Email	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 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
}

Extend your software with TaxBandits IRS E-file API Integration