Skip to main content
Version: 1.7.3

RequestByBusinessURL

RequestByBusinessURL

This is a payee-initiated method that allows you to generate a single secure URL for a specific business (payer) or DBA. You can embed this link into your portal, platform, or email—allowing any payees (recipients) to access and complete their W-9 or W-8 form without requiring a unique invitation.

note

If you prefer to generate individual secure URLs for each payee, use the RequestByUrl endpoint instead.

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/W-8 request, ensure at least one business (payer) has been created using the Business endpoint. This is a mandatory step.

3. Call the [POST] WhCertificate/RequestByBusinessUrl endpoint​

Your request must include the following:

  • Authorization Header - Include the Bearer token obtained from OAuth.
  • Payee Email Address - The form completion secure URL will be sent here.
  • Payee Reference (Optional) - A unique ID for referencing the payee in future API calls.
  • Payee Name and Address (Optional) - If included, this info will be pre-filled in the form.
  • 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.

4. Payee completes the form​

  • TaxBandits API will generate a unique URL for the business (or DBA) and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the payees to click.
  • Upon clicking the secure URL, the payee will be provided with the option to choose the Form W-9, W-8BEN, W-8BEN-E, or W-8ECI based on their citizenship and resident status. They can complete, e-sign, and submit the form.
URL Parameterization for Tracking Vendor Submissions:

To facilitate a better tracking of W-9/W-8 submissions, TaxBandits API allows you to add a reference to the common secure URL. By appending a PayeeRef parameter to the secure URL, you can associate submissions with specific vendors. Learn More.

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


If you want to validate the TINs automatically once collected, you can set the IsTINMatching as TRUE in your request JSON.

POST WhCertificate/RequestByBusinessURL
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestobject[]SubmissionManifest provides brief information about submission and the services opted for.
   IsTINMatchingBooleanIf set as True, TIN Matching service will be enabled. Once the recipient signs the Form W-9, TaxBandits will validate the recipient’s Name, TIN, and TINType with the IRS.
   UrlValiditystringExpiration date for the generated secure URL.
format: MM/DD/YYYY or MM-DD-YYYY Example: 01/25/2025 or 01-25-2025
   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 Business Logo, Primary color, Secondary color, etc.
      BusinessLogoUrlstringOptional Gets the Business Logo. If given the business logo will be shown in the Form page.
Size Range: ..150
      LogoPositionstringOptional Gets the position in which the logo should be displayed.
Allowed values

"LEFT", "CENTER", "RIGHT"

      InterviewFlowBooleanOptional If TRUE, your vendors will fill the W-9 in an interview flow instead of the traditional Form filling flow.
      PrimaryColorstringOptional Gets the primary color for the portal. You can use this to customize the color theme of the portal to match with your application color
      SecondaryColorstringOptional Gets the secondary color for the portal. You can use this to customize the color theme of the portal to match with your application color
    PrefLangStringOptionalGets the default display language for the portal. If not set, English will be shown.
Allowed values

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

RequesterobjectCollects the Requestor identifier i.e., TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed as the Requester.
   BusinessIdGuidTaxBandits 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.
   PayerRefstringOptional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
   TINstringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values

"EIN", "SSN" (Including hyphen)

   DBAIdGuidUnique Identifier for the DBA.
   DBARefstringUnique identifier for each DBA. This identifier can be used in future references of the DBA in the API.

Response Body

FieldTypeDescription
SecureUrlstringReturns the Secure URL generated by TaxBandits for the particular business
RequesterobjectReturns the requestor identifier i.e., TIN or TBS Business Id or PayerRef
   BusinessIdGuidReturns the unique Business Identifier
   PayerRefstringReturns the unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL
   TINstringReturns the Taxpayer Identification Number
Size Range: 9-11
   DBAIdGuidReturns the unique Identifier for the DBA
   DBARefstringReturns the unique identifier for each DBA. This identifier can be used in future references for the DBA in the API
Errorsobject[]Collection of errors
   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​

Generate a secure W-9/W-8 URL for a particular payer (business).

{
  "SubmissionManifest": {
      "IsTINMatching": true,
      "UrlValidity": "08/27/2024",
      "CustomizationId": null,
      "Customization": {
          "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
          "LogoPosition": "RIGHT",
          "InterviewFlow": false,
          "PrimaryColor": "#21DF9A",
          "SecondaryColor": "#323F92",
          "PrefLang": "es-ES"
      }
  },
  "Requester": {
      "BusinessId": "32416f37-b16c-4a6e-9c73-9f974ace75b6",
      "PayerRef": null,
      "TIN": null
  }
}

Response JSON​

This is a sample response for successful API requests.

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