Skip to main content
Version: 1.7.3

RequestByBusinessUrl

RequestByBusinessUrl

This method generates a single, public URL tied to a specific payer (business or DBA). Unlike the other request methods, this URL is not unique per recipient (payee) — it can be shared broadly, embedded on your website, or included in onboarding emails. Any recipient who completes the form through this URL is automatically linked to that payer in TaxBandits.

This is the most scalable collection method when you can't enumerate recipients in advance or want to minimize the number of API calls needed to collect forms.

When to use​

  • You are onboarding a large number of vendors and cannot issue individual URL requests for each one.
  • You have a high volume of new vendors or contractors signing up regularly, and want a zero-touch collection path.

If you need each recipient to receive a personalized invitation with their name and details pre-filled, use RequestByEmail or RequestByUrl instead.

RequestByEmail / RequestByText / RequestByUrlRequestByBusinessUrl
Who initiatesPayer—you trigger the request per recipient.Recipient (Payee)—you publish the URL once, and they access it on their own.
URL scopeUnique per recipient.Shared across all recipients.
API callsRequires one API call per recipient.After the initial URL generation, no API calls are required.

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 exists

    Before calling this endpoint, confirm the payer has been created using the Business endpoint. If no BusinessId is provided in the request,you will receive an error.

  3. Call the endpoint

    Your request may include the following optional parameters:

    • DBAId / DBARef — Scope the URL to a specific DBA under the business. The DBA name will appear as the requester on the form.
    • UrlValidity — Set an expiration date for the URL.
    • Customization — Apply your logo, primary/secondary colors, and logo position to brand the form page. Alternatively, pass a CustomizationId generated from the Portal Customization endpoint.
    • PrefLang — Specify the language for the form. Supported languages: English, French, Spanish, German, Ukrainian, and Portuguese.
    • InterviewFlow — Present the W-9 as a guided interview rather than a traditional form.
    Automate TIN Matching

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

  4. Embed or share the URL

    The API returns a SecureUrl in the response — a public URL tied to the specified payer or DBA. Deploy the URL in your onboarding flow, a vendor self-service portal, an automated welcome email, or a QR code on a printed document.

    Since this is a public URL, we recommend you enable OTA verification in Developer Console → Settings → W-9/W-8 Settings to ensure secure submissions.

  5. Recipient completes the form

    When a recipient opens the URL, they are prompted to select the form appropriate for their status — W-9, W-8BEN, W-8BEN-E, W8IMY, W8EXP, or W-8ECI — and then complete, e-sign, and submit it.

  6. Get notified

    Once a recipient submits, you can receive the result 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.
    Tracking submissions with URL parameterization

    Because all recipients share the same base URL, TaxBandits provides URL Parameterization to track individual submissions. Append your internal identifier (such as PayeeRef) for each payee as a query parameter to associate the submissions with specific recipients. Learn more.

POST WhCertificate/RequestByBusinessUrl
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestobject[]Contains submission details.
IsTINMatchingBooleanSet to TRUE to automatically trigger IRS TIN Matching once the payee submits their form.
UrlValiditystringExpiration date for the generated URL. After this date, the link is no longer accessible.
Format: MM/DD/YYYY or MM-DD-YYYY Example: 01/25/2025 or 01-25-2025
CustomizationIdGuidA unique identifier for a saved customization profile, generated via the Developer Console or the PortalCustomization endpoint. Applies your branding to the form page.
CustomizationobjectInline branding settings applied to the form page. Use this if you don't have a CustomizationId.
BusinessLogoUrlstringURL of the logo to display on the form page.
Maximum size: 150px
LogoPositionstringPosition of the logo on the form page.
Allowed values

"LEFT", "CENTER", "RIGHT"

PrimaryColorstringPrimary color for the form page, matched to your platform's color theme.
SecondaryColorstringSecondary color for the form page.
InterviewFlowBooleanSet to TRUE to present the W-9 as a step-by-step interview instead of the traditional form layout.
PrefLangStringDefault display language for the form. Payees can change their preferences during completion.
Allowed values

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


Defaults to “en-US”.
RequesterobjectIdentifies the payer associated with this URL. If omitted, the URL is generated for the default (first) business in your account.
BusinessIdGuidTaxBandits' unique identifier for the payer, returned when the business was created.
PayerRefstringYour own unique identifier for the payer, assigned when creating the business.
Size Range: 1-50
TINstringTaxpayer Identification Number of the payer.
Allowed values

"EIN", "SSN" (Including hyphen)

Size Range: 9-11
DBAIdGuidUnique identifier for a specific DBA under the business. The DBA name will appear as the requester on the form.
DBARefstringYour own reference identifier for the DBA. Can be used in future API calls to reference the same DBA.

Response Body

FieldTypeDescription
SecureUrlstringThe public shared URL generated for the specified payer or DBA. Embed this in your portal or platform for payees to access.
RequesterobjectReturns the payer identifiers associated with the generated URL.
BusinessIdGuidTaxBandits’ unique identifier for the payer.
PayerRefstringYour unique identifier for the payer, as provided in the request.
TINstringTaxpayer Identification Number of the payer.
DBAIdGuidUnique identifier for the DBA, if the URL was scoped to one.
DBARefstringYour reference identifier for the DBA, if provided in the request.
Errorsobject[]Array of error objects returned if the request fails. Null on success.
IdstringTaxBandits-assigned unique identifier for the error.
NamestringThe name of the field or node where the error occurred.
MessagestringA description of the error.

Request JSON​

Generate a business URL scoped to a DBA
Scope the collection URL to a specific DBA so that the DBA's name appears as the requester on the form.

{
  "SubmissionManifest": {
      "IsTINMatching": true,
      "UrlValidity": "08/27/2024",
      "CustomizationId": "e4e3db3a-5032-4646-97d1-8d0837f43189",
      "Customization": {
          "BusinessLogoUrl": null,
          "LogoPosition": null,
          "InterviewFlow": false,
          "PrimaryColor": null,
          "SecondaryColor": null
      }
  },
  "Requester": {
      "BusinessId": "86b2ea22-c928-42ef-a5fe-545a09072fdc",
      "PayerRef": null,
      "TIN": "26-3537385",
      "DBAId": "6aaba0bc-ec93-4a21-a600-f1733f76130e",
      "DBARef": "Ref008"
  }
}

Response JSON​

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

{
  "SecureUrl": "https://snowda_388311.esignw9.com",
  "Requester": {
      "BusinessId": "99cdf439-8037-4fbf-a2d2-aad0409337d5",
      "PayerRef": "pay5465",
      "DBAId": null,
      "DBARef": null
  },
  "Errors": null
}