Skip to main content
Version: 1.7.3

RequestByText

RequestByText

This is a payer-initiated method that allows you to send a text message containing a unique secure URL to each payee (recipient) for completing forms like W-9, W-8BEN, W-8BEN-E, W-8IMY, W-8ECI or W-8EXP.

Note:

You are required to provide the recipient's phone number along with their country code. If no country code is provided, the default will be the US country code.

How it works​

1. OAuth 2.0 Authentication​

As with any TaxBandits API call, begin by authenticating through the OAuth 2.0 flow to obtain an access token. This token must be included in the request header as a Bearer token. Refer to the OAuth 2.0 Authentication guide for details on JWT authentication and token handling.

2. Create Business​

Before initiating a W-9 or other form request, ensure at least one business (payer) has been created using the Business endpoint. This is a mandatory step.

3. Call the [POST] WhCertificate/RequestByText Endpoint​

Your request must include the following:

  • Authorization Header - Include the Bearer token obtained from OAuth.
  • Recipient's Phone Number: The form completion secure URL will be sent via text.
  • Recipient's Country Code: This is required to send the request via SMS. If no country code is provided, the default will be the US country code.
  • Business Identifier (Optional) - Provide the BusinessId or TIN to identify the payer associated with the request. If omitted, the form will be tied to the first business in your account.
  • DBA Reference (Optional) - Used to display a specific DBA name as the requester on the form.
  • Customizations (Optional) - You may include branding customization in the request, such as logo, theme colors, etc, and the redirection URLs where you want the payee to be redirected once they submit the form. You may also include a CustomizationId if you’ve generated one. Learn more
  • Languages (Optional) – Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian and Portuguese

4. Recipient Completes the Form​

TaxBandits will send a text message with a secure URL to the recipient. Once the recipient clicks the secure URL, they can complete the form, e-sign, and submit it.

5. Get notified​

  • Webhooks - If you’ve configured Webhooks for the event type 'WhCertificate Status Change Webhook', you will receive a webhook notification once the payee submits the form. The Webhook payload includes payee details (name, TIN, address) and a link to download the completed form. Learn more
  • Status endpoint - Alternatively, you can also use the Status endpoint to retrieve the status.
  • Web messaging - Instead of Webhooks, you can choose to receive notifications via web messaging. For more information, click here.
Automate TIN Matching


To validate the TINs automatically once collected, set the IsTINMatching field to true in your request. This will trigger TaxBandits to validate the recipient’s TIN with the IRS and notify you of the results.

POST WhCertificate/RequestByText
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestObject[]SubmissionManifest provides brief information about submission and the services opted for.
IsTINMatchingBooleanOptional TIN Matching will be enabled when the value is set as True. Once the recipient completes Form W-9, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify the client via the webhook with the TIN results.
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 TaxBandits Unique Business Identifier. This ID is 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 alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values

"EIN", "SSN" (Including hyphen)

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.
    PayeeRefStringOptionalA 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
    PhoneStringThe phone number of the recipient
Size Range: 4-16
    CountryPhoneCodeStringRecipient’s country code. If not provided, the US will be selected by default.
Size Range: 2
Allowed values

"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"

    AddressObjectOptionalCollects 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 Recipient 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
    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.
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.
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 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.
    PrefLangStringOptionalLanguage Preference of the form
Allowed values

"en-US", "es-ES", "fr-FR","de-DE","uk-UA","pt-PT"

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
    FirstNmStringFirst Name of the Individual
Size Range: ..20
    MiddleNmStringMiddle Name of the Individual
Size Range: ..20
    LastNmStringLast Name of the Individual
Size Range: ..20
    SuffixStringSuffix of the Individual
Allowed values

"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"

    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.
        PhoneStringThe phone number of the recipient
        CountryPhoneCodeStringRecipient’s country code.
        WhCertificate StatusStringStatus of the WhCertificate
        StatusTsStringTimestamp of the WhCertificate status
    ErrorRecordsObjectDetails of the recipients with errors
        PayeeRefStringA Unique identifier of the recipient.
        PhoneStringThe phone number of the recipient
        CountryPhoneCodeStringRecipient’s country code.
        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.

Request JSON​

{
  "SubmissionManifest": {
    "IsTINMatching": true
  },
  "Requester": {
    "BusinessId": "959763e4-26d3-4d52-a8eb-b954b22616fd",
    "PayerRef": "Pay025",
    "TINType": "EIN",
    "TIN": "39-4589707",
    "DBAId": null,
    "DBARef": null
  },
  "Recipients": [
    {
      "PayeeRef": "payeeref016",
      "Name": "Shawn Williams",
      "CountryPhoneCode": "US",
      "Phone": "5687657876"
    }
  ],
  "WebhookRef": null,
  "CustomizationId": "D6ACC1C4-74E5-4A60-B569-77F4612BD988",
  "Customization": {
    "InterviewFlow": true,
    "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
    "LogoPosition": "CENTER",
    "PrimaryColor": "#1321E6",
    "SecondaryColor": "#0F700C",
    "PrefLang": "es-ES"
  }
}

Response JSON​

{
  "SubmissionId": "2d1797a2-5e56-4da4-a59d-e82e858ffbd8",
  "Requester": {
      "BusinessId": "9e284b90-aa98-4287-8e9a-38cc590a90d3",
      "BusinessNm": "Snowdaze LLC",
      "PayerRef": "Pe12rtgr3",
      "TINType": "EIN",
      "TIN": "39-4589707"
  },
  "WhCertificate": {
      "SuccessRecords": [
          {
              "PayeeRef": "T@122",
              "Phone": "5687657876",
              "CountryPhoneCode": "US",
              "WhCertificateStatus": "ORDER_CREATED",
              "StatusTs": "2022-06-14 07:05:18 +05:30"
          },
          {
              "PayeeRef": "mia@345",
              "Phone": "5687657746",
              "CountryPhoneCode": "US",
              "WhCertificateStatus": "ORDER_CREATED",
              "StatusTs": "2022-06-14 07:05:18 +05:30"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}