Collect recipient tax data

To file a recipient's forms, Taxbit needs their legal name, TIN, and address. This page is the API path, for tax data you already hold. To have recipients fill in a W-9 or W-8 inside your app instead, use the Tax Documentation React SDK.

One account owner carries the tax data for all of that recipient's accounts, so you collect it once per recipient, not once per account.

By the end of this page you have a recipient's name, TIN, and address on their account owner, their W-9 data submitted, and a way to check whether their documentation is valid.

Before you begin

• A bearer token. See Authenticate your tenant.
• The recipient's account owner. See Create account owners and accounts.
• The recipient's legal name, TIN, and address, and, for a signed W-9 or W-8, the answers and certification from the form.

Add name, TIN, and address to the account owner

Update the account owner with the recipient's details. The TIN goes in tax_residencies, one entry per country the recipient is taxed in; the top-level tin, tin_type, and tax_country_code fields are deprecated. Send only the fields you are setting.

curl -X PATCH $BASE_URL/v1/account-owners/usr_8a3b1c9d \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Whitfield",
    "tax_residencies": [
      { "country": "US", "tin": "123456789", "tin_type": "SSN" }
    ],
    "address": {
      "first_line": "1810 Alder Lane",
      "city": "Portland",
      "state_or_province": "OR",
      "postal_code": "97205",
      "country": "US"
    }
  }'

A 200 returns the updated account owner in data. Country fields take a two-letter code; see Country fields.

An account can carry its own mailing_address and prefers_physical_mail, which take precedence over the account owner's for that account. See the Accounts reference.

Submit W-9 or W-8 data

When a recipient has completed a W-9 or W-8 outside the SDK, submit the form's data to the endpoint for that form. A submission is stored as tax documentation alongside the account owner; it does not overwrite the account owner's name, TIN, or address. When Taxbit builds the recipient's forms, the name and TIN come from a valid W-form, and the address comes from whichever source has a valid address, or the newer source otherwise. A W-form that isn't valid loses that priority: the name follows the same rule as the address, and the TIN comes from the account owner when it has a complete one, otherwise from the newer source.

No W-9 field is required. The W-8 endpoints require only irs_version, the IRS revision the form was collected against (2021_OCT), and W-8BEN and W-8BEN-E also accept a substitute form without it. Taxbit validates whatever you send and reports anything missing or invalid as issues in the documentation status.

A W-9 for an individual:

curl -X POST $BASE_URL/v1/account-owners/usr_8a3b1c9d/tax-documentation-data/w-9 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Whitfield",
    "tax_classification": "INDIVIDUAL",
    "address": {
      "first_line": "1810 Alder Lane",
      "city": "Portland",
      "state_or_province": "OR",
      "postal_code": "97205",
      "country": "US"
    },
    "tin": "123456789",
    "tin_type": "SSN",
    "is_not_subject_backup_withholding": true,
    "has_signed_and_certified": true,
    "signature_timestamp": "2026-03-02T16:10:00Z"
  }'

A 201 returns the submitted data in data. The W-8 endpoints take the fields of their form; the Tax Documentation reference has each schema.

To update a recipient's form, submit a new one with a newer signature_timestamp. Taxbit keeps every submission and treats the one with the latest signature date as current, so a resubmission dated earlier than the current form is stored but doesn't replace it.

Check the documentation status

Read the recipient's status across every form type, including W-9, W-8BEN, W-8BEN-E, and W-8IMY forms submitted through the endpoints above.

curl $BASE_URL/v1/account-owners/usr_8a3b1c9d/tax-documentation-status \
  -H "Authorization: Bearer $TOKEN"

• submission_status is SUBMITTED once any tax documentation is on file for the account owner, otherwise NOT_SUBMITTED.
• w_form_questionnaire covers the W-9 and W-8: type names the form (W-9, W-8BEN, W-8BEN-E, or W-8IMY), tax_documentation_status is VALID or INVALID, tin_status is the result of TIN validation (W-9 only), needs_resubmission says whether to ask the recipient for a new form, and issues lists what needs fixing.

GET /v1/account-owners/{id}/tax-documentation-data returns the submitted data itself, with sensitive values masked unless you pass unmask=true.

If the request fails

• 400. A field failed validation. The message names the field.
• 401. The bearer token is missing, invalid, or expired. Mint a new one and retry.
• 404. No account owner has that id. Create it first, as Create account owners and accounts shows.
• 429. Too many requests. Slow down and retry.

Parameters

Only the fields used above. The full schemas are in the Account Owners reference and the Tax Documentation reference.

PATCH /v1/account-owners/{id}

POST /v1/account-owners/{id}/tax-documentation-data/w-9

Where to go next

Retrieve US tax forms shows how to get each recipient's forms once Taxbit has generated them.