Skip to main content
Version: 1.7.1

RequestByEmail

RequestByEmail

This is a payer-initiated method wherein our API endpoint will be used to send an email request to the payees for the completion of W-9 forms.

This endpoint sends a unique URL via email to enable the payees to complete their W-9 Forms. In order to generate this unique URL, the payee’s email address is 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 it 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. The second step is to call the [POST] FormW9/RequestByEmail endpoint with the following values:
    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API).
    • 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.
    • Business Logo (Optional) - You can customize the business logo on the Form W-9.
    • Requester (Business Id or TIN) (optional) - 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 provide a Business id or TIN in the request, the W-9 will be associated with the default business, i.e., the first business created in your account.
  3. TaxBandits will send the W-9 request emails to the payees. The email will have the link to complete Form W-9.
  4. The payees will complete and e-sign Form W-9 in a secured portal. The secured portal can be white-labeled with your URL, logo, and theme.
  5. Once the payee completes and signs the Form W-9, you will be notified via Webhook. The Webhook payload will have the W-9 information, such as the name, address, EIN/SSN, etc., along with the link to download the completed Form W-9.

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

  1. If IsTINMatching is set to ‘TRUE’, TaxBandits will validate the payee’s TIN against the IRS database.
POST FormW9/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestobjectSubmissionManifest 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, i.e., TIN (or) Business ID/PayerRef generated by TaxBandits. If neither is supplied, the default Business will be assumed as the Requester.
    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 the BusinessId in the request, then 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 alternate for BusinessId. (Values: EIN, SSN)
Size Range: 9-11
Recipientsobject[]Collects the recipient's unique identifier and other basic information that will be pre-filled on the Form.
    PayeeRefStringOptional A unique identifier for each recipient completing the Form W-9 for future references.
Size Range: 1-50
    NamestringName of the recipient.
Size Range: ..40
    EmailstringEmail Address of the recipient. This is the email address to which the W-9 request email will be sent.
Size Range: ..100
    AddressObjectCollects US address details of the recipient.
        Address1stringOptional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..46
        Address2stringOptional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..46
        CitystringOptional Recipient US City. This will be pre-filled on the Form.
Size Range: ..46
        StatestringOptional OptionalRecipient US State Code. This will be pre-filled on the Form.
Size Range: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"

        ZipCdstringOptional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5..10
CustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization process in the Developer console or the unique ID you received in the response of the PortalCustomization CREATE Endpoint. endpoint.
Note: You can customize the W-9/W-8 page (secure URL) with your own logo, favicon, and primary and secondary colors.
EmailCustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization process in the developer console.
Note: You can customize the W-9/W-8 request email template with your own logo, favicon, and primary and secondary colors.
CustomizationObjectOptional Collects the customizations like TIN service, Business Logo and Callback URLs.
    BusinessLogoUrlStringOptional Gets the Business Logo. If given the business logo will be shown in the Iframe page.
Size Range: ..150
    LogoPositionStringOptional Optional The position where your business logo will be placed on the page.
Allowed values

"LEFT", "CENTER", "RIGHT"

    InterviewFlowBooleanOptional As an alternative to direct-form entry, provide your recipients with an interview-style W-9/W-8 completion.
    PrimaryColorStringOptional The color theme of the iframe page will be customized with this primary color.
    SecondaryColorStringOptional The color theme of the iframe page will be customized with this secondary color.

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.
    TINTypeStringTIN Type of the Requester.
    TINStringTaxpayer Identification Number of the requester.
FormW9RecordsObjectDetails of Form W-9 requests given in the request.
    SuccessRecordsObject[]Recipients 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
        PayeeRefStringA 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.
Example :
  • You should have at-least one business in your account to request W-9
  • 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.

Request JSON​

Pass the BusinessId, recipient’s name,email address and customizations. 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",
 "PayerRef": null,
 "TIN": null
},
"Recipients": [
 {
   "PayeeRef": "8987844654654654",
   "Name": "Allen Smith",
   "Email": "allen.smith@abc.com",
   "Address": {
     "Address1": "1751 Kinsey Rd",
     "Address2": "Main St",
     "City": "Dothan",
     "State": "AL",
     "ZipCd": "36303"
  }
 }
],
"Customization": {
  "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png"
}
}

Response JSON​

The response will contain the W-9 request for the recipient included in the submission with the customizations updated on the W-9 page. When a recipient submits the FORM W-9, the Form W-9 Status Change Webhook payload will include the W-9 data.

{
  "SubmissionId": "54755d41-4883-4ae6-9bf5-48d8482b50a1",
  "Requester": {
      "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
      "PayerRef": "aATT12",
      "BusinessNm": "Express Solutions",
      "TINType": "EIN",
      "TIN": "00-7711148",
      "DBAId": null,
      "DBARef": null
  },
  "FormW9Records": {
      "SuccessRecords": [
          {
              "PayeeRef": "1",
              "Email": "allen.smith@abc.com",
              "W9Status": "ORDER_CREATED",
              "StatusTs": "2023-10-26 01:32:01 -04:00"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}