Skip to main content
Version: 1.7.3

RequestByUrl

RequestByUrl

This is a payee-initiated method where the API generates a unique secure URL per recipient. You can share the URL directly with recipients or embed it in your platform as an iframe, and recipients can complete the form on their own.

When to use​

  • You want recipients to access and complete the form on their own, without sending a direct email or SMS invitation.
  • You want to embed the form completion experience directly into your platform as an iframe, keeping recipients within your application.

If you want a single shared URL for all recipients under a payer, use RequestByBusinessUrl 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.
    • ShowDownloadPage — Set to TRUE to give recipients the option to download their completed 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

    The API returns a Url in the response — a unique, recipient-specific secure URL. You can:

    • Embed it in your application or portal as an iframe.
    • Share it directly with the recipient via your own email, SMS, or messaging system.

    When the recipient opens 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/RequestByUrl
Run in Postman

Request Body

FieldTypeDescription
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
FedTaxClassStringOptional Federal tax classification of the recipient. Pre-filled on the form.
NameStringOptional Recipient's name. Pre-filled on the form.
Size: 1–50
IsForeignBooleanOptional Set to TRUE if the recipient has a foreign address. When TRUE, pass address details under ForeignAddress instead of USAddress.
USAddressObjectOptional Recipient's US 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
ForeignAddressObjectOptional Recipient's foreign address. Required when IsForeign is TRUE.
Address1StringOptional Street address or PO Box.
Size: 1–50
Address2StringOptional Suite or apartment number.
Size: 1–50
CityStringOptional City.
Size: 1–50
ProvinceOrStateNmStringOptional Province or state name.
Size: 1–50
PostalCdStringOptional Postal code.
Size: 1–16
IsTINMatchingBooleanOptional Set to TRUE to automatically trigger IRS TIN Matching once the recipient submits their W-9.
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.
ShowDownloadPageBooleanOptional Set to TRUE to give recipients the option to download their completed form after submission.
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"

RedirectUrlsObjectOptional Redirect settings after form submission or cancellation.
ReturnUrlStringOptional URL to redirect the recipient after successfully submitting the form.
Size: 1–150
CancelUrlStringOptional URL to redirect the recipient if they click cancel. If not provided, the cancel button is not shown.
Size: 1–150
RedirectTimeNumberOptional Time in seconds before the redirect occurs.
Size: 5–300

Response Body

FieldTypeDescription
SubmissionIdGuidTaxBandits-generated unique identifier for this submission.
PayeeRefStringYour unique identifier for the payer.
UrlStringThe unique secure URL generated for this recipient. Embed it in your portal or share it directly.
Errorsobject[]List of error details if the request failed. Null on success.
IdstringTaxBandits-assigned error code.
NamestringField or node that triggered the error.
MessagestringHuman-readable error description.

Request Json​

Request URL with TIN Matching and redirect URLs
Generate a secure URL with the recipient's details pre-filled, TIN Matching enabled to validate their TIN on submission, and redirect URLs configured.

{
  "Requester": {
      "PayerRef": null,
      "BusinessId": null,
      "TIN": null,
      "DBAId": null,
      "DBARef": null
  },
  "Recipient": {
      "PayeeRef": "SG7356",
      "FedTaxClass": "INDIVIDUAL",
      "Name": "David Smith",
      "IsForeign": true,
      "USAddress": {
          "Address1": "1751 Kinsey Rd",
          "Address2": "Main St",
          "City": "Dothan",
          "State": "AL",
          "ZipCd": "36303"
      },
      "ForeignAddress": {
          "Address1": "1751 Kinsey Rd",
          "Address2": "Main St",
          "City": "Dothan",
          "ProvinceOrStateNm": "TN",
          "Country": "IN",
          "PostalCd": "641016"
      },
      "IsTINMatching": true
  },
  "Customization": {
      "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
      "LogoPosition": "CENTER",
      "InterviewFlow": true,
      "PrimaryColor": "#1be6f5",
      "SecondaryColor": "#9c9276",
      "ShowDownloadPage": true
  },
  "RedirectUrls": {
      "ReturnUrl": "https://example.com",
      "CancelUrl": "https://example.com",
      "RedirectTime": 60
  }
}

Response JSON​

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

{
  "SubmissionId": "7971f12e-fc8f-4d88-91c9-deb4696d3612",
  "PayeeRef": "123456",
  "Url": "https://testlinks.taxbandits.io?whId=7b20d2c0-6585-435c-89c7-3a01b13d33ef",
  "Errors": null
}