Validation API guide

Send Taxbit tax documentation you collected yourself.

Send Taxbit tax documentation you collected yourself.

The Validation API is for teams that already collect W-9s, W-8s or self-certifications in their own forms, systems or onboarding flows. You send Taxbit the data; Taxbit stores it as the account owner's tax documentation, reviews it, and reports anything that needs fixing on the account owner's status and in the Taxbit dashboard.

📘

Want Taxbit to run the questionnaire instead?

With the Validation API, your team owns the questions, the wording and the checks. If you'd rather use Taxbit's ready-made questionnaire, see the React SDK. To compare every option, see the Tax documentation overview.

How it works

  1. You collect the data in your own UI or systems.
  2. You send it to the endpoint for that form. Any well-formed request is accepted and stored, even if the data is incomplete.
  3. Taxbit reviews it after it's stored. Anything missing or invalid becomes an issue on the account owner's tax documentation status and in the Taxbit dashboard.
  4. You fix what's flagged by going back to the person and sending a corrected, complete form.

The submit response doesn't tell you whether the data is valid. A 201 means Taxbit stored it. Read the status to find out whether it's ready for reporting.

Before you start

  • Create the account owner first. Every form belongs to an account owner. Submitting for an unknown id returns 404.
  • Get a tenant token. These are server-to-server calls. Your server requests a tenant token with your client ID and secret and sends it as Authorization: Bearer <token>. A tenant token lasts 24 hours.

Submit a form

{id} is your own identifier for the account owner. Field names are snake_case.

POST /v1/account-owners/acct-owner-123/tax-documentation-data/w-9
Authorization: Bearer <tenant token>
Content-Type: application/json

{
  "name": "Robert Smith",
  "tax_classification": "INDIVIDUAL",
  "address": {
    "first_line": "123 Main St",
    "city": "Salt Lake City",
    "state_or_province": "UT",
    "postal_code": "84101",
    "country": "US"
  },
  "tin": "123456789",
  "tin_type": "SSN",
  "has_signed_and_certified": true,
  "signature_timestamp": "2026-11-17T18:30:00Z"
}

A 201 returns the stored submission in data, with sensitive values such as TINs masked.

Signing

Send has_signed_and_certified: true and the signature_timestamp when the person signed. signature is the name as signed; leave it out and Taxbit uses name for an individual (tax_classification: INDIVIDUAL). Collecting the certification itself, with the IRS wording, is part of your form.

Sending a newer form

A submission with a later signature_timestamp replaces the person's current form. One with an earlier timestamp is stored but doesn't replace it. A submission is stored as tax documentation and doesn't change the account owner's own name, TIN or address.

What gets rejected

Only a request Taxbit can't read: malformed JSON, an unknown field, a value of the wrong type or outside its allowed values, or a date that can't be parsed. That returns 400 with issues naming each field. Missing or inconsistent data isn't rejected; it's stored and flagged.

Check the status

GET /v1/account-owners/{id}/tax-documentation-status returns the status of the current form for every form type the account owner has. Call it whenever you need the current status, for example before paying out or filing. To hear about changes instead of polling, subscribe to the ACCOUNT_OWNER_TAX_DOCUMENTATION_STATUS webhook, which carries the same status whenever it changes.

{
  "w_form_questionnaire": {
    "type": "W-9",
    "data_collection_status": "COMPLETE",
    "tax_documentation_status": "INVALID",
    "needs_resubmission": false,
    "issues": [
      {
        "issue_type": "INCOMPLETE_US_TIN",
        "status": "OPEN",
        "created_at": "2026-11-17T18:31:02.000Z",
        "details": [
          { "field": "tin", "description": "…" }
        ]
      }
    ]
  }
}
FieldWhat it tells you
tax_documentation_statusVALID, or INVALID when the form has issues to fix before it can be used for reporting
issuesWhat's wrong, each with an issue_type, a status (OPEN, IN_REVIEW, RESOLVED) and details naming each field
needs_resubmissionYou've asked for a new form and it hasn't arrived yet
data_collection_statusCOMPLETE or INCOMPLETE

The same issues appear on the account owner in the Taxbit dashboard. See Tax documentation issues and warnings for what each issue means.

Fix an issue

Go back to the person, collect the corrected information, and submit the complete form again. The status reports on the current form: the one with the latest signature_timestamp, so give the corrected form the date the person signed it. Once a corrected form is current, the issues on the earlier one no longer appear.

To flag that you need a new form from someone, for example after a change in circumstances, request new documentation. The status shows needs_resubmission: true until a new form arrives, and the current form stays valid in the meantime. Revoke the request if you no longer need it.

Read back what's stored

Seller data (DPS)

There's no DPS submit endpoint. To send seller information you already hold for DAC7 or MRDP, update the account owner with it, or upload a CSV through the Ingest page in the Taxbit Dashboard. See Collect seller data.

Guides by reporting regime

These walk through the same endpoints for a specific kind of reporting:

Limits

By default, each method and route allows 100 requests per second with a burst of 1,000, per organization. Over the limit returns 429. See Errors and rate limits.