Common Workflows — TaxBandits
W-9/W-8 API

TaxBandits supports multiple ways to collect W-9 and W-8 forms depending on your platform architecture, recipient experience, and the level of control you want over the collection flow. This guide documents each method as a complete workflow — covering the full sequence of API calls, recipient actions, and system events from start to finish.

Each workflow is designed to be self-contained. You can implement one method or combine several, based on your use case.

Table of Contents:

• Collecting a W-9 Before Paying Vendors (RequestByEmail)
• Collecting a W-9 During Vendor Onboarding (RequestByUrl)
• Embedded W-9 Collection Within Your Application (Drop-In UI)
• Self-Serve Collection via Public URL
• Bulk Migration of Existing Forms

1. Collecting a W-9 Before Paying Vendors (RequestByEmail)

Send a W-9 request directly to vendors via email when a form is required before making a payment or completing compliance checks. This approach works well for platforms that trigger collection based on payout events or missing tax information.

You can also use RequestByText to send the same secure link via SMS for faster, mobile-friendly completion.

When to use

Your platform manages vendor payments. When a new vendor is approved or invited, you need to collect a W-9 before you can issue payments or 1099s.

How it works

1. Payout or onboarding triggers the workflow

   A vendor exceeds an IRS-reportable payment threshold, or is newly approved in your system. Your platform logic determines that a W-9 is required before the next payment can be issued.

2. Call FormW9/RequestByEmail

   Send the vendor's name, email address, and — optionally — a CustomizationId to brand the email with your sender name, from-address, and logo. TaxBandits generates a unique Secure URL for this vendor and dispatches the email immediately.

3. Vendor receives the email and completes the form

   The vendor clicks the secure link in the email and lands on the form completion page. They fill in their TIN, legal name, address, and tax classification, then e-sign and submit. No TaxBandits account is required.

4. TIN Matching runs in the background (if enabled)

   If IsTINMatching was set to TRUE in the request, TIN validation runs automatically after the vendor submits. The process checks the TIN and legal name against IRS records. No additional API call is needed from your side.

5. Webhook fires with the submission result

   The payload includes the SubmissionId, submission status, TIN matching result, and a PDF URL for the completed form.

6. Your system acts on the result

   Mark the vendor as tax-form-complete in your system. If TIN matching returned "Success", release any held payments. If "Failed", flag the vendor for review and trigger a corrected request.

7. Handle non-response

   If the vendor has not submitted after a reasonable period, call FormW9/Status to check whether the link was opened. Use ExpireLink to invalidate the old link, then call RequestByEmail again to send a fresh request.

2. Collecting a W-9 During Vendor Onboarding (RequestByUrl)

Generate a secure, vendor-specific W-9 link and embed it directly within your portal during onboarding or account setup. This allows vendors to complete the form within your application flow without needing a separate email trigger.

When to use

This is the most common workflow for businesses that provide a dedicated portal or account for vendors, where form collection is part of the onboarding process.

How It Works

1. Vendor reaches the W-9 step in your portal

   The vendor is logged into your portal and navigates to a payout setup, onboarding, or account verification page where a W-9 is required.

2. Call FormW9/RequestByUrl (server-side)

   Your backend calls RequestByUrl with the vendor's details. The API returns a unique Secure URL for this vendor. This URL is tied to one recipient — it cannot be reused for a different vendor. Optionally set IsTINMatching=TRUE to trigger TIN validation on submission.

3. Embed the Secure URL as an <iframe> in your portal page

   Render the Secure URL in an iframe within your portal's W-9 step. The vendor sees the form as part of your application — same browser tab, same page context. The form page inherits no TaxBandits branding unless you have not configured customization.

4. Vendor fills the W-9 and e-signs

   The vendor completes their legal name, TIN, address, and tax classification inside the iframe and submits. TIN Matching runs automatically in the background if enabled.

5. Receive notification

   Three notification paths are available:

   • Webhook: Your backend receives the full submission payload with status, TIN result, and PDF URL.
   • Status: Call the Status endpoint to retrieve the status.
   • Web Messaging (postMessage): Your parent application receives a browser-level event immediately on submission — use this to update the portal UI in real time without polling.

6. Verify TIN and complete onboarding

   If TIN matching is “Success” (or if TIN matching is not required), mark the vendor's W-9 step as complete and advance them to the next stage of onboarding.

3. Embedded W-9 Collection Within Your Application (Drop-In UI)

Embed a fully branded W-9 form directly inside your application for a seamless, in-product experience. This method provides maximum control over UI and ensures tax collection feels native to your platform.

When to use

You want to avoid the appearance of any third-party redirect, and your platform has strict Content Security Policy (CSP) requirements.

How It Works

1. Detect that no W-9 is on file

   The vendor opens a payout, onboarding, or account settings page. Your application checks its records and determines that a valid W-9 is not on file for this vendor. The Drop-In UI flow begins.

2. Construct a JWS token (server-side)

   On your backend, build a JSON Web Signature (JWS) token using the HS256 algorithm. Encode your Client ID as the issuer (iss), subject (sub), and audience (aud), and include the current Unix timestamp as the issued-at (iat) claim. Use your Client Secret to sign the token. Your API credentials are available in Developer Console → Settings → API Credentials.

3. Exchange the JWS for a transient token

   Call the Drop-In UI authentication endpoint with the JWS. In the request body, include the allowed origin domains — the domains where your application will load the embedded form. TaxBandits returns a transient token valid for 15 minutes, scoped to those domains via a Content Security Policy frame-ancestors directive.

4. Initialize the Drop-In UI in your frontend

   Pass the transient token to the TaxBandits Drop-In SDK. Include the PayeeRef that identifies this vendor in your system, and provide any UI customization options — colors, fonts, button styles, label text. The SDK loads the form within your application's frame.

5. W-9 form renders inside your application

   The form loads natively inside your page — styled to match your product. The vendor sees no TaxBandits branding unless you choose to include it. All configuration (PayeeRef, UI settings, TIN matching) is encrypted before being passed to the iframe. Sensitive inputs never pass through your frontend.

6. Vendor fills the W-9 and submits

   The vendor completes their information and e-signs inside the embedded form. All data is captured directly by TaxBandits via end-to-end encryption.

7. Receive notification

   • Webhook: Your backend receives the full submission payload with status, TIN result, and PDF URL.
   • Status: Call the Status endpoint to retrieve the status.

8. Handle token expiry

   The transient token expires 15 minutes after it is issued. If the vendor opens the page but delays loading the form — for example, by leaving the tab idle — the token may expire before the form renders. In this case, your backend should request a new transient token and re-initialize the Drop-In UI.

To enable TIN Matching for the Drop-In UI, contact developer@taxbandits.com.
TIN validation is configured at the account level for Drop-In — it cannot be toggled per-request. Once enabled, it fires automatically on every submission.

4. Self-Serve Collection via Public URL (RequestByBusinessUrl)

Provide a reusable public link that allows recipients to submit W-9/W-8 forms independently at any time. Ideal for platforms that cannot predict which recipients will need to submit a form, or that want a persistent collection link with no per-recipient setup.

When to use

Affiliate programs, public vendor registration pages, etc.

How It Works

1. Generate a business URL once per payer

   Call WhCertificate/RequestByBusinessUrl for a given payer. This returns a single persistent Secure URL that can serve all recipients for that payer. You do not need to call this endpoint again unless the payer changes. Store the URL — it does not expire.

2. Append a PayeeRef before distributing (Optional)

   When sharing the URL with a specific recipient — in an email, on a dashboard, or via an invitation — append their unique identifier as a query parameter: ?payeeref=YOUR_VENDOR_ID

   This is the only mechanism for mapping a submission back to a specific vendor.

3. Publish the URL via any channel

   Embed the Secure URL (with PayeeRef appended) in your vendor registration page, bulk onboarding email, or vendor dashboard. Recipients access the form on their own schedule — no session or prior account is required.

4. Recipient completes the form

   The recipient opens the link, is presented with the appropriate W-9 (or W-8 form if using the WhCertificate endpoint), fills in their information, e-signs, and submits. TIN Matching runs automatically if enabled via Developer Console.

5. Webhook returns the PayeeRef

   Your configured webhook endpoint receives a ‘WhCertificate Status Change’ event. The payload includes the PayeeRef you appended to the URL, allowing you to map the submission back to the correct vendor record in your database. Update the vendor's status to tax-form-complete.

6. Handle submissions without a PayeeRef

   If a recipient accesses the public URL directly — without a PayeeRef appended — the submission is still captured, but it will not be automatically mapped to a vendor. Use the List endpoint to retrieve all recent submissions and reconcile any unlinked records manually.

5. Bulk Migration of Existing Forms (WhCertificate/Create)

Import existing W-9/W-8 records into TaxBandits without requiring recipients to re-submit their information.

When to use

You already hold completed, signed W-9 or W-8 forms from recipients and want to register them in TaxBandits for downstream 1099 filing — without asking recipients to re-submit.

How It Works

1. Prepare your existing vendor tax records

   Export or compile your current vendor data: TIN, legal name, address, federal tax classification, and the signed PDF form if you hold a scanned or digitally signed copy. Ensure each record includes all required fields before submitting.

2. Call WhCertificate/Create per record

   Post the structured form data in the request body for each vendor. Supported form types include W-9, W-8BEN, W-8BEN-E, W-8ECI, W-8IMY, and W-8EXP. If you have a signed PDF, include the PdfUrl field pointing to where the document is hosted. TaxBandits creates a recipient record and returns a unique RecipientId.

3. TIN Matching runs on import (W-9 only)

   If IsTINMatching is set to TRUE in the request, TIN validation runs automatically after each import. The result is returned in the API response. No separate webhook event is needed for the TIN result, though the webhook will still fire for status changes if configured.

4. Handle TIN mismatch results

   If TIN matching returns “Flagged” for a vendor, flag their record in your system. Trigger a fresh RequestByEmail request to collect corrected information directly from the vendor. Do not proceed with 1099 filing for records with unresolved TIN mismatches.

5. Link shared vendors across multiple payers

   If a vendor works with more than one payer on your platform, you do not need to import the same record separately for each payer. After the initial import, call LinkWhCertificate with the vendor's RecipientId to associate their existing form with additional payers. This avoids duplicate collection and keeps records consolidated.