Skip to main content
Version: 1.7.3

RequestByText

RequestByText

This is a payer-initiated method where the API sends a secure, personalized text message to each recipient containing a unique URL to complete their W-9 form. Every URL is scoped to that specific recipient and cannot be accessed by anyone else. This option is helpful if your recipients are more likely to respond to an SMS than an email.

You must provide the recipient's phone number in the request. If no country code is provided, the US country code is used by default.

If you want to reach recipients via email, use RequestByEmail instead.

How it works​

  1. Authenticate

    Obtain a Bearer token via the OAuth 2.0 flow and include it in all request headers.

  2. Ensure a business (payer) exists

    Before calling this endpoint, confirm the payer has been created using the Business endpoint. If no BusinessId is provided in the request, the request will be associated with the default payer (the first payer created in your account).

  3. Call the endpoint

    Along with the payer and recipient details, your request may include the following optional parameters:

    • DBAId / DBARef — Scope the URL to a specific DBA under the payer. The DBA name will appear as the requester on the form.
    • Customization — Apply your logo and primary/secondary colors to brand the form page. Alternatively, pass a CustomizationId generated from the PortalCustomization endpoint.
    • InterviewFlow — Set to TRUE to present the W-9 as a guided interview rather than a traditional form.
    • PrefLang — Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian, and Portuguese.
    Automate TIN Matching

    Set IsTINMatching to TRUE to automatically trigger IRS TIN Matching once the recipient submits their form.

  4. Recipient completes the form

    TaxBandits sends the email request to the recipient. When the recipient opens the secure URL, they can complete, e-sign, and submit Form W-9 online.

  5. Get notified

    Once a recipient submits, you can receive notification through any of the following:

    • Webhooks — Configure the Form W-9 Status Change webhook event to receive a payload with the recipient's name, TIN, address, and a link to download the completed form. Learn more
    • Status endpoint — Poll the Status endpoint on demand to retrieve the current form status for a given recipient.
    • Web messaging — Receive in-browser notifications when a recipient completes their form. Learn more
POST FormW9/RequestByText
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestobjectSubmissionManifest 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, i.e., TIN (or) Business ID/PayerRef generated by TaxBandits. If neither is supplied, the default Business will be assumed as the Requester.
PayerRefStringOptional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByText.
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.
TINTypeStringOptionalTIN Type of the Requester.
TINStringOptional Taxpayer Identification Number. Use this as an alternate for BusinessId. (Values: EIN, SSN)
Size Range: 9-11
Allowed values

"EIN", "SSN" (Including hyphen)

DBAIdStringOptional Unique Identifier for the DBA.
DBARefStringOptional Unique identifier for each DBA. This identifier can be used in future references of the DBA in the API.
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
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"

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.
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.
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"

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
FormW9RecordsObjectDetails of Form W-9 requests given in the request.
SuccessRecordsObject[]Recipients with no error in the request
PayeeRefStringUnique identifier of the recipient.
PhoneStringThe phone number of the recipient
CountryPhoneCodeStringRecipient’s country code.
W9StatusStringStatus of the W-9
StatusTsStringTimestamp of the W-9 status
ErrorRecordsObjectDetails of the recipients with errors
PayeeRefStringA unique identifier of a 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 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​

{
"SubmissionManifest": {
 "IsTINMatching": true",
 "TINType": "EIN",
 "PayerRef": "FJK123W",
},
"Recipients": [
 {
   "PayeeRef": "8987844654654654",
   "Name": "Mark Davis",
  "CountryPhoneCode": "US",
  "Phone": "5687657876"
  "Address": {
        "Address1": "201 KATLIAN ST",
        "Address2": "STE. 108",
        "City": "SITKA",
        "State": "AK",
        "ZipCd": "99835"
    }
 }
]
}

Response JSON​

Success Response - This is a sample response for successful API requests.

{
  "SubmissionManifest": {
      "IsTINMatching": true
  },
  "Requester": {
            "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8"
  },
  "Recipients": [
      {
          "PayeeRef": "ER001",
          "Name": "Mark Davis",
          "CountryPhoneCode": "US",
          "Phone": "5687657876"
      }
  ]
}