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 or W-8 form. Every URL is scoped to that specific recipient and cannot be accessed by anyone else.

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.

When to use​

  • Your recipients are more likely to respond to an SMS than an email.
  • You are collecting forms from recipients outside the US and have their country phone codes available.

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 SMS to each recipient. When they open the link, they select the applicable form — W-9, W-8BEN, W-8BEN-E, W-8ECI, W-8IMY, or W-8EXP — and complete, e-sign, and submit it.

  5. Get notified

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

    • Webhooks — Configure the 'WhCertificate 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 WhCertificate/RequestByText
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestObjectSubmission-level settings for this request.
IsTINMatchingBooleanOptional Set to TRUE to automatically trigger IRS TIN Matching once the recipient submits their W-9.
RequesterObjectIdentifies the payer associated with this request. If omitted, the default payer in your account is used.
PayerRefStringOptional Your unique identifier for the payer.
Size: 1-50
BusinessIdGuidOptional TaxBandits-generated unique identifier for the payer.
TINStringOptional Taxpayer Identification Number of the payer. Can be used in place of BusinessId or PayerRef.
Size: 9-11
DBAIdStringOptional Unique identifier for the DBA. The DBA name appears as the requester on the form.
DBARefStringOptional Your reference identifier for the DBA.
Size: 1-50
RecipientObject[]List of recipients to send the text request to. Each element represents one recipient.
PayeeRefStringOptional Your unique identifier for the recipient, used to reference them in future API calls.
Size: 1-50
NameStringOptional Recipient's name. Pre-filled on the form.
Size: 1-50
PhoneStringMobile phone number of the recipient. The collection SMS is sent to this number.
Size: 4-16
CountryPhoneCodeStringOptional Recipient's country phone code. Defaults to the US country code if not provided.
Size: 2
AddressObjectOptional Recipient's mailing address. Pre-filled on the form.
Address1StringOptional Street address or PO Box.
Size: 1-46
Address2StringOptional Suite or apartment number.
Size: 1-46
CityStringOptional City.
Size: 1-46
StateStringOptional Two-letter state code.
Size: 2
ZipCdStringOptional ZIP code. Format: 99999 or 99999-9999.
Size: 5-10
WebhookRefGuidOptional Unique identifier for a specific webhook callback URL configured in the Developer Console. If omitted, the response is posted to the default callback URL.
CustomizationIdGuidOptional A unique identifier for a saved customization profile, generated via the Developer Console or the PortalCustomization endpoint. Applies your branding to the form page.
CustomizationObjectOptional Inline branding settings for the form completion page. Use this if you do not have a CustomizationId.
BusinessLogoUrlStringOptional URL of the logo to display on the form page.
Size: 1-150
LogoPositionStringOptional Position of the logo on the form page.
Allowed values

"LEFT", "CENTER", "RIGHT"

InterviewFlowBooleanOptional Set to TRUE to present the W-9 as a guided step-by-step interview instead of the traditional form layout.
PrimaryColorStringOptional Primary brand color for the form page.
SecondaryColorStringOptional Secondary brand color for the form page.
PrefLangStringOptional Default display language for the form. Defaults to English if not set.
Allowed values

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

Response Body

FieldTypeDescription
SubmissionIdGuidTaxBandits-generated unique identifier for this submission.
RequesterObjectPayer details associated with this request.
BusinessIdGuidTaxBandits-generated unique identifier for the payer.
BusinessNmStringPayer name. Returns the business name if the payer is an entity, or the full name if the payer is an individual.
FirstNmStringFirst name of the payer (individual).
Size: 1-20
MiddleNmStringMiddle name of the payer (individual).
Size: 1-20
LastNmStringLast name of the payer (individual).
Size: 1-20
SuffixStringSuffix of the payer (individual).
PayerRefStringYour unique identifier for the payer.
TINTypeStringTIN type of the payer.
TINStringTaxpayer Identification Number of the payer.
DBAIdStringUnique identifier for the DBA.
DBARefStringYour reference identifier for the DBA.
WhCertificateObjectResults of the W-9/W-8 collection requests submitted in this call.
SuccessRecordsObject[]Recipients for whom the request was successfully processed.
PayeeRefStringYour unique identifier for the recipient.
PhoneStringMobile number to which the SMS was sent.
CountryPhoneCodeStringCountry phone code of the recipient.
WhCertificateStatusStringCurrent status of the W-9/W-8 request.
StatusTsStringTimestamp of the last status update.
ErrorRecordsObject[]Recipients for whom the request failed.
PayeeRefStringYour unique identifier for the failed recipient.
PhoneStringMobile number provided for the failed recipient.
CountryPhoneCodeStringCountry phone code provided for the failed recipient.
ErrorsObject[]List of error details for this recipient.
IdStringTaxBandits-assigned error code.
NameStringField or node that triggered the error.
MessageStringHuman-readable error description.
ErrorsObject[]Top-level errors that prevented the entire submission from being processed. Null on success.
IdStringTaxBandits-assigned error code.
NameStringField or node that triggered the error.
MessageStringHuman-readable error description.

Request JSON​

Send a text request to a recipient linked to a specific payer
Send a W-9/W-8 collection SMS to a recipient's mobile number and associate the completed form with a specific payer using BusinessId.

{
  "SubmissionManifest": {
      "IsTINMatching": true
  },
  "Requester": {
      "BusinessId": "959763e4-26d3-4d52-a8eb-b954b22616fd",
      "PayerRef": null,
      "TIN": null,
      "DBAId": null,
      "DBARef": null
  },
  "Recipients": [
      {
          "PayeeRef": "ER001",
          "Name": "Shawn Williams",
          "CountryPhoneCode": "US",
          "Phone": "5897657876"
                
}
  ],
  "WebhookRef": null,
  "CustomizationId": null,
  "Customization": null
}

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": "2025-06-14 07:05:18 +05:30"
          },
          {
              "PayeeRef": "mia@345",
              "Phone": "5687657746",
              "CountryPhoneCode": "US",
              "WhCertificateStatus": "ORDER_CREATED",
              "StatusTs": "2025-06-14 07:05:18 +05:30"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}