Skip to main content
Version: 1.7.3

RequestByBusinessURL

Generate a common public URL for a specific business (payer) or a specific DBA of the business, integrate it into your website, and make it accessible to your payees/vendors. They can use the link to complete and submit their W-9/W-8 forms. To obtain this URL, you must send an API request using the BusinessId or PayerRef.

note

Alternatively, you can generate individual secure URLs for each payee using the RequestByUrl method.

How does this work?​

  1. OAuth 2.0 Authentication - Call the Auth method to get the access token. This access token must be supplied in the request header as the 'Bearer' token. Refer to OAuth 2.0 Authentication for more information on JWT authentication.
  2. Call the [POST] WHCertificate/RequestByBusinessURL endpoint - The request JSON must contain the following parameters:
    • Access Token in the header
    • Business Identifier - You must supply the BusinessId, a unique identifier generated by TaxBandits when a business is created. Refer to the Business endpoint to learn more. You can also include PayerRef and TIN if you prefer.
    • DBA Reference (Optional) - If you are required to obtain the URL for a particular DBA, you must provide the corresponding DBAId and DBARef.
    • Business Logo and Callback URLs (Optional) - You can provide your business logo and callback URLs for customization.
    • Customizations (Optional) - You can provide the following things in your request for customization.
      • Business Logo - You can provide your business logo and its position.
      • Color Theme - Specify the primary and secondary colors of the page.
      • Interview-Style - As an alternative to direct-form entry, provide your recipients with an interview-style W-9/W-8 completion.
  3. URL generation and form completion - 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 recipients to click. Upon clicking, the recipient will be provided with the option to choose the Form W-9 or W-8BEN based on their citizenship and resident status. Accordingly, Form W-9 or W-8BEN will be shown with built-in validations. An electronic signature pad allows the recipient to sign and submit the form electronically.
  4. Webhook Notification - Once the recipient completes and signs the form, you will be notified via Webhooks. If the node WebhookRef in the request JSON has a Webhook Reference ID, the Webhook response will be posted to the corresponding Callback URL.
    The webhook payload will have the following recipient data:
    • For W-9 - Name, address, email, TIN Matching status, form data, PDFURL to download the completed form, etc.
    • For W-8BEN - Name, country, address, and reduced tax rate.
    • Form W-8BEN-E - Name, country, entity, TIN, Tax benefits, etc.
      Refer to Form WhCertificate webhook to learn more about webhook setup and sample payload.
  5. If IsTINMatching is set to 'TRUE', TaxBandits will validate the payee's Name, TIN, and TINType against the IRS database. The TIN Matching status of the payee (Success or Failed) will be posted on the same Webhook URL configured for 'WhCertificate Status Change'. If the name and TIN given by the payees do not match the IRS database, the W-9/W-8 will become invalid, and you have to request a new Form W-9/W-8 from the respective payee.
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: 10/20/2023 or 10-20-2023
   CustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization in the console.Note: You can customize the W-9/W-8 page (secure URL) with your own logo, fav icon, primary and secondary colors, and email.
   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
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.

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"
        }
    },
    "Requester": {
        "BusinessId": "32416f37-b16c-4a6e-9c73-9f974ace75b6",
        "PayerRef": null,
        "TIN": null
    }
}

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

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