Guides

How the SDK works

This is the complete picture — what the SDK is, how a submission flows end to end, what's supported, and where it fits in your product. It's the read-through companion to the Integration guide, which covers step-by-step setup.

What the SDK is

The SDK collects tax documentation inside your own React app. It's two primitives:

  • TaxbitQuestionnaire — a component that renders the right questionnaire, walks the user through it, validates input, and submits to Taxbit.
  • useTaxbit — a hook that exposes the resulting status and generated documents so you can reflect them in your UI.

You mint a short-lived, per-user token on your server and optionally pass data to pre-fill. Taxbit owns the form logic, jurisdiction rules, validation, and document generation.

The TaxbitQuestionnaire component rendered with default styling (left) and embedded inside a branded host application (right)

For local development, demoMode={true} runs the component with no token and no API calls — everything else in this doc applies once you switch to a real token.

The end-to-end lifecycle

A submission moves through eight stages:

  1. Provision — your server creates an Account Owner for the user.
  2. Authorize — your server mints an Account Owner-scoped token and passes it to the browser.
  3. Render — TaxbitQuestionnaire mounts with that token and any pre-fill data.
  4. Collect — the user answers only the questions Adaptive can't already satisfy.
  5. Submit — once the form passes client-side validation, onSubmit fires, then onSuccess on Taxbit's confirmation (or onError on failure), and onSettled after either.
  6. Validate — TIN (W-9) and VAT (DPS) checks run asynchronously, resolving in minutes to hours.
  7. Report — final status arrives through useTaxbit and webhook events.
  8. Re-collect — if circumstances change, needsResubmission sends the user back through the same component.

The sections below explain the model behind these stages; the Integration guide implements them.

The security and token model

The SDK is split across a trust boundary. Your server holds the client_secret and obtains a tenant-scoped token, then exchanges it for an Account Owner-scoped token — narrow authority for one person. Only that narrow token reaches the browser. If it leaks, the blast radius is one Account Owner for at most 24 hours.

sequenceDiagram
    participant Server as Your Server
    participant Taxbit as Taxbit API
    participant Client as Your React App

    Server->>Taxbit: POST /v1/oauth/token
    Taxbit-->>Server: tenant-scoped bearer token (24h)

    Server->>Taxbit: POST /v1/account-owners
    Taxbit-->>Server: 201 Created

    Server->>Taxbit: POST /v1/oauth/account-owner-token
    Taxbit-->>Server: Account Owner-scoped bearer token (24h)

    Server->>Client: Pass Account Owner-scoped token

    Client->>Taxbit: <TaxbitQuestionnaire /> submits form
    Taxbit-->>Client: Success

Account Owners and Accounts

The SDK operates on an Account Owner — the person whose documentation you collect. An Account is separate: it represents a transactional relationship, not a person, and is used for transaction reporting. The SDK doesn't require one.

The questionnaires

Three questionnaire types, by reporting regime:

  • W-FORM — U.S. forms (W-9, W-8BEN, W-8BEN-E, W-8IMY)
  • DPS — digital-platform-seller reporting (DAC7 and equivalents)
  • SELF-CERT — self-certification of tax residency for CRS, CARF, and DAC8 reporting

The choice is driven by your reporting obligations and the user's status. To map a situation to a type, see Pick your questionnaire.

Adaptive collection

The SDK can shorten the flow by skipping questions you already have valid answers for, so returning users move faster. A few fields — signatures, controlling-person data on entity Self-Cert — are always re-collected regardless of pre-fill.

See Adaptive mode for the modes (full, skipLock, skipEdit), skip rules, and per-form data shapes.

Where to embed

Two primary patterns:

Onboarding flow. Embed the SDK at the end of signup so a W-form is on file before the account is funded or any reportable events occur. This is the most common pattern for platforms with regulatory collection requirements at onboarding.

Account Profile / Settings. Embed the SDK in the account settings area for on-demand collection. This works well when tax documentation is not required at signup but may be needed later (for example, when a reporting threshold is crossed).

What's supported

Platforms

React 16-19 and TypeScript 5, in modern browsers. The component calls the Taxbit API from the browser, so your Content Security Policy must allow it — see Connect your backend for the directive.

Mobile

There's no native iOS or Android SDK. On mobile you render the component in a webview and bridge its callbacks to native code, passing the Account Owner token to the webview page. See mobile webview embedding for platform-specific components and UX guidance.

Languages

The questionnaires localize automatically. See the supported-language matrices for the full lists, per-form coverage, and the language prop.

Updated about 16 hours ago