---
updatedAt: 2026-10-13T22:23:47.000Z
agentTools:
projectIndex: https://apidocs.taxbit.com/llms.txt
---
# Component and hook reference
Props, hooks, types, status enums, callbacks, and CSS customization for [`@taxbit/react-sdk`](https://www.npmjs.com/package/@taxbit/react-sdk). For setup, see the [Questionnaire integration guide](https://apidocs.taxbit.com/docs/integration-guide).
# `` props
The primary component for collecting tax documentation. Import it from `@taxbit/react-sdk` and render it in your React application.
| Prop | Type | Required | Default | Description |
| -------------------------- | ------------------------------------------------------ | --------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bearerToken` | `string` | Yes\* | — | Account Owner–scoped token for API communication. Not required when `demoMode` is `true`. |
| `questionnaire` | `'W-FORM' \| 'DPS' \| 'SELF-CERT'` | Yes | — | Which questionnaire to render. See [Pick your questionnaire](https://apidocs.taxbit.com/docs/integration-guide#pick-your-questionnaire) for guidance on choosing. |
| `data` | `ClientTaxDocumentation` | No | — | Pre-collected data to populate form fields. Overrides server-fetched data if both exist. |
| `adaptiveMode` | `'full' \| 'skipLock' \| 'skipEdit'` | No | `'full'` | How prefilled answers are used. `full` (default): nothing hidden; answers filled in. `skipLock`: questions with valid answers are hidden and locked on the summary. `skipEdit`: questions with valid answers are hidden, and everything stays editable on the summary. See [Adaptive mode](https://apidocs.taxbit.com/docs/integration-guide#adaptive-mode-skip-pre-filled-questions). |
| `prepopulateWithSavedData` | `boolean` | No | `true` | When `true` (default), the SDK fetches the account owner's prior submission on mount, prefills the form, and routes returning users to the summary. Set to `false` to skip that fetch — no saved PII is requested on mount and the form starts on step one. Does not affect host-supplied `data`, status reads, or submission. See [Skip server-side prefill](https://apidocs.taxbit.com/docs/integration-guide#skip-server-side-prefill). |
| `language` | `string` | No | `'en-us'` (W-FORM), `'en-gb'` (DPS, SELF-CERT) | Pre-selects the form language. See [supported languages](#supported-languages). |
| `treatyClaims` | `boolean` | No | `false` | W-FORM only (W-8 flows). Set to `true` if your clients are foreign persons claiming reduced US withholding rates under an income tax treaty. Enables treaty claim questions in W-8BEN and W-8BEN-E flows. Omit to skip treaty claims entirely. |
| `fatca` | `boolean` | No (see notes) | `false` | Available in `5.0.0` and later. W-FORM only. Enables FATCA (Chapter 4) collection: classification, certifications, GIIN capture, and substantial US owner collection where applicable. Forced to `true` when `typesOfIncome` includes `INTEREST` or `DIVIDENDS` — setting `fatca={false}` in that case throws at initialization. See [Enable FATCA collection](https://apidocs.taxbit.com/docs/integration-guide#enable-fatca-collection). |
| `typesOfIncome` | `TypeOfIncome \| string \| (TypeOfIncome \| string)[]` | Yes if `treatyClaims` | — | Available in `5.0.0` and later. W-FORM only. Income types the filer's account can generate. Drives treaty-eligibility filtering. Accepts hyphenated (`'royalties-other'`) or underscored (`'ROYALTIES_OTHER'`) forms. Unrecognized values throw at initialization. Some values (`INTEREST`, `DIVIDENDS`) also force `fatca={true}`. See [Accepted values](https://apidocs.taxbit.com/docs/integration-guide#accepted-values) for the full list. |
| `realTimeTinValidation` | `boolean` | No | `false` | W-FORM only (W-9). Validates the account owner's name and TIN against the IRS in real time. The account owner can still proceed if no match. Requires RTT configuration. In demo mode, TINs containing `0` return valid, `6` return invalid, otherwise pending. |
| `eDeliveryConsent` | `boolean` | No | `false` | Available in `6.3.0` and later. W-FORM only (W-9 and every W-8). Adds a checkbox to the Review and Sign section of the summary asking the account owner to consent to receiving their tax forms electronically. The label holds the full consent statement. The box starts checked, is never required, and is never pre-filled from a prior submission. The answer is submitted as `hasEDeliveryConsent` (`true` checked, `false` cleared, absent when this prop is off), and `config.eDeliveryConsent` records whether consent was collected. |
| `demoMode` | `boolean` | No | `false` | Renders the form without server communication. No bearer token required. Only `onProgress` and `onSubmit` apply in demo mode. See [Set up locally](https://apidocs.taxbit.com/docs/integration-guide#set-up-locally). |
| `region` | `'US' \| 'EU'` | No | `'US'` | Routes SDK API requests to the selected Taxbit region. |
| `proxyDomain` | `string` | No | — | Routes every request through your own proxy instead of directly to Taxbit. Can't be combined with `region`. |
| `proxyHeaders` | `Record` | No | — | Extra headers on proxied requests. Your proxy must strip them. `authorization` and `content-type` are reserved and overwritten. |
| `telemetry` | `boolean` | No | `true` | Available in `6.2.0` and later. Sends usage events (steps shown, button presses, validation errors shown, real-time check outcomes; never what the user typed) to `telemetry/events` with the same token and host as other requests. Failed events never interrupt the form. `false` sends nothing; demo mode sends nothing. See [Usage telemetry](https://apidocs.taxbit.com/docs/integration-guide#usage-telemetry). |
| `dateFormat` | `'mdy' \| 'dmy' \| 'ymd'` | No | `'mdy'` | Order of date-of-birth select inputs when displayed. |
| `loadingComponent` | `ReactNode` | No | Text: "Retrieving interview status..." | Shown while the SDK fetches status and the first language, and when rendered on the server. |
| `poweredByTaxbit` | `boolean` | No | `false` | When `true`, shows "Powered by Taxbit" at the bottom of the form. |
| `onProgress` | `(progress: Progress) => void` | No | — | Called when the user navigates (Next, Back, Cancel, Submit). Receives a [Progress](#progress) object. Fires once per event, so an inline function is fine. |
| `onSubmit` | `(data: ClientTaxDocumentation) => void` | No | — | Called after the form passes client-side validation, before the API request completes. Fires whether or not the save succeeds; use `onSuccess` to act on a saved submission. From `6.3.0`, `accountHolder.phoneNumber` is in E.164 form (`+447872615090`), and `hasEDeliveryConsent` is included when `eDeliveryConsent` is on. |
| `onSuccess` | `(data: ClientTaxDocumentation) => void` | No | — | Called after the API confirms successful submission. |
| `onError` | `(error: Error) => void` | No | Logs to console | Called when the API returns an error. If omitted, the error is logged to the console and shown in the SDK's error alert — not rethrown. From `6.3.0`, a failed submission keeps the form and answers on screen and shows "Your Tax Documentation could not be saved. Please try again." above Submit, so the user can retry; `onError` still receives the error. Not called for telemetry failures. Fires once per event, so an inline function is fine. |
| `onSettled` | `(data: ClientTaxDocumentation) => void` | No | — | Called after either `onSuccess` or `onError`. |
# Resubmission behavior
On mount the component fetches any prior submission for the questionnaire type and adapts:
| Previous status | Behavior |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `COMPLETE` | Shows the summary screen immediately for review/edit. |
| `INCOMPLETE`, prior submission exists | Walks each screen with prior data pre-filled (e.g. earlier validation failure or changed requirements). |
| `INCOMPLETE`, no prior submission | Walks each screen from the start; nothing to pre-fill. |
| `data` prop + server data | The `data` prop wins. |
**Partial progress is not saved.** The SDK persists only on submit — closing or navigating away mid-flow discards entries and leaves `dataCollectionStatus` unchanged. The server sets `INCOMPLETE` when a submission fails validation or previously valid data no longer meets requirements, not on an abandoned session. Use `statusData.needsResubmission` as the canonical signal to route a user back through.
# `` props
A focused component that clears specific W-8 validation issues in place. Import it from `@taxbit/react-sdk`. For the full embedding walkthrough, see the [Curing integration guide](https://apidocs.taxbit.com/docs/curing-integration-guide).
```jsx
import '@taxbit/react-sdk/style/inline.css';
import { TaxbitCuringDocumentation } from '@taxbit/react-sdk';
```
The component accepts one of three prop shapes. Exactly one applies per call site.
## Common to all shapes
| Prop | Type | Required | Default | Description |
| ----------------- | --------- | -------- | ------- | --------------------------------------- |
| `language` | `Locale` | No | `en-us` | Pre-selects the form language. |
| `poweredByTaxbit` | `boolean` | No | `false` | Renders the "Powered by Taxbit" footer. |
## Demo mode
Renders against a synthesized issue list. No network calls, no token.
| Prop | Type | Required | Default | Description |
| ---------------- | ---------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `demoIssueTypes` | `CurableIssueType[]` | Yes | — | Open issues to render. Status is assumed `OPEN`. Doc type is fixed to W-8BEN-E. |
| `onSubmit` | `(submission: ClientCuringSubmission) => void` | No | — | Fires when the user submits. Receives the canonical submission shape. |
## Production — region (default)
| Prop | Type | Required | Default | Description |
| ------------------ | ---------------------------------------------- | -------- | --------------- | --------------------------------------------------------------------------------- |
| `bearerToken` | `string` | Yes | — | Account Owner–scoped token. Same token used by ``. |
| `region` | `'US' \| 'EU'` | No | `'US'` | Regional server for API requests. |
| `loadingComponent` | `ReactNode` | No | `null` | Shown during the initial status fetch and the first language download. |
| `onSuccess` | `(submission: ClientCuringSubmission) => void` | No | — | Fires after the server accepts the multipart POST. Not when the cure is reviewed. |
| `onError` | `(error: Error) => void` | No | Logs to console | Fires on status-fetch or submission error. |
| `onSettled` | `(submission: ClientCuringSubmission) => void` | No | — | Fires after `onSuccess` or `onError`, with the same payload. |
## Production — through a proxy
Same as region, with `region` replaced by:
| Prop | Type | Required | Default | Description |
| -------------- | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------ |
| `proxyDomain` | `string` | Yes | — | Route API requests through your own proxy instead of Taxbit directly. |
| `proxyHeaders` | `Record` | No | — | Custom headers on proxied requests; `authorization` and `content-type` are reserved. |
## Mount-time behavior
On mount, the component fetches `statusData` for the user and derives the curable issue list. The widget renders `null` and emits a dev-mode warning if no `OPEN` curable issue exists. Gate the mount on `useTaxbit().needsCuringDocumentation` to avoid the round-trip.
# `useTaxbit` hook
Read a user's tax documentation status and data without rendering the form, and generate the completed document PDF. Use it to drive your own UI — for example, to decide whether to route someone into `` or to show a "documentation complete" state.
Unlike the component, the hook has no `demoMode`: a valid `bearerToken` is always required.
**Parameters**
| Parameter | Type | Required | Description |
| -------------------------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `bearerToken` | `string` | Yes | Account Owner–scoped token. |
| `questionnaire` | `'W-FORM' \| 'DPS' \| 'SELF-CERT'` | Yes | Which questionnaire's data to access. |
| `onError` | `(error: Error) => void` | No | Error handler. If omitted, errors log to the console. |
| `prepopulateWithSavedData` | `boolean` | No | `false` skips fetching the prior submission; `serverData` stays empty. Default `true`. |
| `region` | `'US' \| 'EU'` | No | Regional server for API requests. Default `'US'`. |
| `proxyDomain` | `string` | No | Route requests through your own proxy. |
| `proxyHeaders` | `Record` | No | Custom headers on proxied requests. |
**Returns**
| Return | Type | Description |
| -------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `statusData` | `ClientTaxDocumentationStatus \| undefined` | Status for this Account Owner (`GET /tax-documentation-status`). |
| `serverData` | `ClientTaxDocumentation \| undefined` | Last submitted data (`GET /tax-documentation/submissions`). Empty object when `prepopulateWithSavedData={false}`. |
| `error` | `Error \| undefined` | Set on a fetch or bearer-token error; logged unless you pass `onError`. |
| `canGetDocumentUrl` | `boolean` | `true` once a W-Form or Self-Cert submission is `COMPLETE` (false while in progress). Always `false` for DPS (no PDF). |
| `generateDocumentUrl` | `() => void` | Triggers PDF URL generation. |
| `isGeneratingDocumentUrl` | `boolean` | `true` between the call and the URL being ready. |
| `documentUrl` | `string \| undefined` | Temporary PDF URL; the hook re-polls about every 4 minutes to keep it fresh. |
| `needsCuringDocumentation` | `boolean` | `true` when the user has at least one `OPEN` W-Form issue the curing flow can resolve. Gate the `` mount on this. |
| `isLoading` | `boolean` | `true` while the status fetch is in flight. Check before reading `needsCuringDocumentation` to avoid a flash of "no curing needed." |
| `refresh` | `() => Promise` | Re-fetches status + submission. Resolves when both settle. Useful after a curing submit so derived state reflects the latest server view. |
| `refreshStatus` | `() => Promise` | Re-fetches status only. Drives `needsCuringDocumentation`. |
| `refreshSubmission` | `() => Promise` | Re-fetches submission only. Drives `serverData`. |
# `useTaxbitStatus` hook
A status-only version of `useTaxbit`. It never fetches the prior submission, so no previously submitted personal data reaches the browser. Use it when you only need to know whether the user must act, for example to decide whether to show ``.
```jsx
import { useTaxbitStatus } from '@taxbit/react-sdk';
const { needsCuringDocumentation, isLoading } = useTaxbitStatus({ bearerToken });
```
**Parameters:** `bearerToken`, `onError`, and `region` or `proxyDomain` + `proxyHeaders`, as for `useTaxbit`. It takes no `questionnaire`; the status covers every questionnaire.
**Returns**
| Return | Type | Description |
| -------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
| `statusData` | `ClientTaxDocumentationStatus \| undefined` | Status for this Account Owner. |
| `isLoading` | `boolean` | `true` while the status fetch is in flight. |
| `error` | `Error \| undefined` | Set on a fetch or bearer-token error. |
| `needsCuringDocumentation` | `boolean` | `true` when there's at least one `OPEN` curable W-8 issue. |
| `refreshStatus` | `() => Promise` | Re-fetches the status. Resolves when the fetch settles. |
# Types
The TypeScript shapes referenced in the props and hook tables above. The SDK exports these, so you can import them for your own typing.
## Progress
The object passed to your `onProgress` callback on every navigation event (Next, Back, Cancel, Submit). Use it to track where the user is in the flow.
```ts
type Progress = {
language: Locale;
percentComplete: number;
stepId: StepId;
stepIndex: number; // 0-based
stepNumber: number; // 1-based
stepTitle: string; // localized
steps: StepId[];
totalSteps: number;
};
```
Common `StepId` values — the active sequence depends on the questionnaire and flow (`Progress.steps` lists what's actually shown).
| StepId | Appears in | Notes |
| ----------------------------------------- | ---------- | ------------------------------------------ |
| `accountHolderClassification` | All | |
| `accountHolderContactInformation` | All | |
| `accountHolderTaxInformation` | All | |
| `accountHolderTaxResidenciesConfirmation` | SELF-CERT | Tax residences in high-risk jurisdictions. |
| `accountHolderCertifications` | W-FORM | |
| `accountHolderTreatyClaims` | W-FORM | W-8 treaty flows. |
| `accountHolderUsTinValidation` | W-FORM | When real-time TIN validation runs. |
| `accountHolderAdditionalInfo` | W-FORM | |
| `exemptions` | W-FORM | |
| `regardedOwnerCertifications` | W-FORM | Disregarded-entity (DRE) flows only. |
| `regardedOwnerContactInformation` | W-FORM | DRE flows only. |
| `regardedOwnerTaxInformation` | W-FORM | DRE flows only. |
| `regardedOwnerTreatyClaims` | W-FORM | DRE flows only. |
| `regardedOwnerUsTinValidation` | W-FORM | DRE flows only. |
| `confirmation` | W-FORM | |
| `summary` | All | |
## ClientTaxDocumentationStatus
Returned by `useTaxbit().statusData`. Each questionnaire key is `undefined` until data is submitted for that type.
```ts
type ClientTaxDocumentationStatus = {
dpsQuestionnaire?: {
dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
expirationDate?: string; // 3 years after last submission
needsResubmission?: boolean;
vatStatus?: VatStatus;
vatValidationDate?: string;
};
wFormQuestionnaire?: {
dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
type: 'W-9' | 'W-8BEN' | 'W-8BEN-E' | 'W-8IMY';
expirationDate?: string;
issues?: QuestionnaireIssue[];
needsResubmission?: boolean;
tinStatus?: TinStatus;
tinValidationDate?: string;
treatyClaimStatus?: 'VALID' | 'INVALID';
};
selfCertification?: {
dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
issues?: QuestionnaireIssue[];
needsResubmission?: boolean;
};
};
```
## Curing types
Types used by `` and the curing read flow. See [Reading curing statuses](https://apidocs.taxbit.com/docs/reading-curing-statuses) for how these surface in practice.
### CurableIssueType
```ts
type CurableIssueType =
| 'US_INDICIA'
| 'TREATY_COUNTRY_MISMATCH'
| 'CARE_OF_PERMANENT_ADDRESS'
| 'PO_BOX_PERMANENT_ADDRESS';
```
Which doc types each applies to:
| Issue type | W-8BEN | W-8BEN-E | W-8IMY |
| --------------------------- | :----: | :------: | :----: |
| `US_INDICIA` | ✓ | ✓ | ✓ |
| `TREATY_COUNTRY_MISMATCH` | ✓ | ✓ | — |
| `CARE_OF_PERMANENT_ADDRESS` | — | ✓ | ✓ |
| `PO_BOX_PERMANENT_ADDRESS` | — | ✓ | ✓ |
### ReasonableExplanationType
```ts
type ReasonableExplanationType =
| 'STUDENT'
| 'TEACHER_OR_TRAINEE'
| 'DIPLOMAT'
| 'SPOUSE_OR_CHILD'
| 'DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST'
| 'CLOSER_CONNECTION_EXCEPTION';
```
Only relevant when the user has an open `US_INDICIA` issue. The first four require no additional fields. `DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST` adds the SPT day-count fields. `CLOSER_CONNECTION_EXCEPTION` adds the closer-connection fields.
### ClientCuringSubmission
```ts
type ClientCuringSubmission = {
fileName?: string;
fileMimeType?: string;
reasonableExplanationData?: {
explanationType: ReasonableExplanationType;
signatureName?: string; // populated from the prior submission's accountHolder.name
signatureDate?: string; // ISO timestamp, stamped at submit
// Present only when explanationType === 'DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST'
daysInCurrentYear?: number;
daysInFirstPrecedingYear?: number;
daysInSecondPrecedingYear?: number;
weightedTotal?: number;
// Present only when explanationType === 'CLOSER_CONNECTION_EXCEPTION'
usPresentDaysCertified?: boolean;
closerConnectionCountryCode?: string;
closerConnectionReason?: string;
};
};
```
Same shape across demo `onSubmit` and production `onSuccess` / `onSettled`.
# Status enums
The string values that appear on the status fields above (`tinStatus`, `vatStatus`, and questionnaire `issues`). Match against them to decide what to show or do next.
## TinStatus
IRS TIN validation; W-9 only.
| Value | Meaning |
| --------------------- | -------------------------------------------- |
| `PENDING` | Submitted, not yet validated. |
| `VALID_SSN_MATCH` | SSN matches IRS records. |
| `VALID_EIN_MATCH` | EIN matches IRS records. |
| `VALID_SSN_EIN_MATCH` | Both SSN and EIN match. |
| `MISMATCH` | Name/TIN doesn't match IRS records. |
| `TIN_NOT_ISSUED` | TIN not issued by the IRS. |
| `INVALID_DATA` | Data malformed or incomplete for validation. |
| `FOREIGN` | Foreign TIN — not validated against IRS. |
| `ERROR` | IRS validation errored. |
## VatStatus
VIES VAT validation; DPS only.
| Value | Meaning |
| ------------------- | ---------------------------------------------------- |
| `PENDING` | Submitted, not yet validated with VIES. |
| `VALID` | VIES confirms valid for the country. |
| `INVALID` | VIES reports invalid. |
| `INSUFFICIENT_DATA` | Not enough data to validate. |
| `NOT_REQUIRED` | User indicated VAT not required or not issued. |
| `NON_EU` | User outside the EU — VAT validation does not apply. |
## Issue status
The `status` field on a curable W-8 issue is its current remediation state (`'OPEN' | 'IN_REVIEW' | 'RESOLVED'`). See [Reading curing statuses](https://apidocs.taxbit.com/docs/reading-curing-statuses).
| Value | Meaning |
| ----------- | -------------------------------------- |
| `OPEN` | The issue still needs to be addressed. |
| `IN_REVIEW` | The issue is being reviewed. |
| `RESOLVED` | The issue no longer applies. |
Transitions: `OPEN → IN_REVIEW` (filer submits), `IN_REVIEW → RESOLVED` (reviewer accepts), `IN_REVIEW → OPEN` (reviewer rejects / requests more). `RESOLVED` is terminal.
## QuestionnaireIssue
Found on `wFormQuestionnaire.issues` and `selfCertification.issues`.
```ts
type QuestionnaireIssue = {
issueType: IssueType;
status: 'OPEN' | 'IN_REVIEW' | 'RESOLVED'; // present on curable W-8 issues
createdAt: string;
details: { field: string; description: string }[];
};
```
| issueType | Applies to | Meaning |
| --------------------------- | ----------------- | ----------------------------------------------------- |
| `CARE_OF_PERMANENT_ADDRESS` | W-FORM | Permanent address uses a c/o format. |
| `PO_BOX_PERMANENT_ADDRESS` | W-FORM | Permanent address is a PO Box. |
| `US_PERMANENT_ADDRESS` | W-FORM | W-8 filer has a US permanent address. |
| `TREATY_COUNTRY_MISMATCH` | W-FORM | Treaty claim country doesn't match residency. |
| `US_INDICIA` | W-FORM, SELF-CERT | Indicators of US-person status detected. |
| `WITHHOLDING_DOCUMENTATION` | W-FORM | Withholding documentation is incomplete. |
| `CHANGE_IN_CIRCUMSTANCES` | W-FORM, SELF-CERT | A change in circumstances requires new documentation. |
| `INCOMPLETE_DATA` | All | Missing required fields. |
| `INCONSISTENT_DATA` | All | Contradictory information. |
| `INCOMPLETE_ADDRESS` | W-FORM, SELF-CERT | Address information is incomplete. |
| `INCOMPLETE_CLASSIFICATION` | W-FORM | Account holder classification is incomplete. |
| `INCOMPLETE_US_TIN` | W-FORM | US TIN is missing or incomplete. |
| `INCOMPLETE_TREATY_CLAIM` | W-FORM | Treaty claim information is incomplete. |
| `CBI_RBI_CONFIRMATION` | SELF-CERT | CBI/RBI confirmation is required. |
| `INCOMPLETE_GIIN` | SELF-CERT | GIIN is missing or incomplete. |
# SDK ↔ API endpoint mapping
The SDK makes these calls for you — useful for debugging and monitoring. Every call goes to the region's API host, or to your `proxyDomain` when one is set.
| SDK action | API behavior | When |
| ----------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| Component mounts / hook initializes | `GET /tax-documentation-status` | On load — checks for existing submissions. |
| Component mounts (data exists) | `GET /tax-documentation/submissions` | On load — fetches prior data for pre-fill. |
| Real-time TIN check | Posts the name and TIN for an inline match | When `realTimeTinValidation` is on. |
| GIIN check | Posts the GIIN for an inline check | When FATCA collects a GIIN. |
| User submits the form | Posts form data to the submission endpoint | On a valid submit. |
| Usage telemetry | Posts usage events | `6.2.0`+, unless `telemetry={false}` or demo mode. Failures are ignored. |
| `generateDocumentUrl()` request | Posts a generate-document request; returns a `documentId` (`PROCESSING`) | When you call it. |
| `generateDocumentUrl()` polling | Polls (\~3s) until `FINISHED` and a URL is available | Automatic after the request. |
The `documentUrl` is short-lived; the hook re-polls about every 4 minutes to refresh it before it expires.
Curing makes these calls:
| SDK action | API behavior | When |
| ------------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Component mounts | `GET /tax-documentation-status` | On load — checks for `OPEN` curable issues. |
| Component mounts | `GET /tax-documentation/submissions` | On load — reads the prior W-8 for the signature name. Skipped when `collectSignatureName` is `true`. |
| User clicks Submit | `POST /account-owner-documents` (multipart) | On submit. `data` part is the snake\_case wire body; the uploaded file is the second multipart part. |
`Content-Type` is left to `fetch` so the multipart boundary survives — don't override it.
# Stylesheets
The form is semantic HTML with `taxbit-` namespaced classes. Import at most one built-in stylesheet, then override classes in your own CSS.
| Stylesheet | Label position | Description |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `inline.css` | beside the input | Full Taxbit default styling — layout, inputs, buttons, badges. |
| `basic.css` | above the input | Same as `inline.css`, with each label on its own line above the field. |
| `minimal.css` | your choice | Structure only — form width, field spacing, status colors. Best base when you intend to restyle. |
| `index.css` | — | Demo-app stylesheet. Styles `:root` and `html`, so it affects your whole page. Not for production. |
`inline.css` and `basic.css` declare their colors as `--taxbit-color-*` custom properties on `:root`; `minimal.css` declares only the four status colors. Override the tokens to theme the form.
For the token list, the full class reference and override patterns, see [Customizing look and feel](https://apidocs.taxbit.com/docs/customizing-look-and-feel).
# Supported languages
The `language` prop accepts any tag in the `Locale` type — the 53 codes below. The account owner can also switch language in-form (hide the dropdown with CSS). The in-form picker shows a subset: roughly 45 in DPS and Self-Certification flows and 19 in W-Form. Defaults are `en-us` (W-Form) and `en-gb` (DPS, Self-Certification).
Only the displayed language is downloaded. Switching language fetches the new one once and keeps the current one on screen until it arrives; if the fetch fails, the current language stays.
## `Locale` tags (53)
| Code | Language | Code | Language | Code | Language |
| ------- | ---------------- | ------- | ------------------- | ------- | --------------------- |
| `bg` | Bulgarian | `fr` | French | `no` | Norwegian |
| `cs` | Czech | `fr-ca` | French (Canada) | `pl` | Polish |
| `da` | Danish | `fr-fr` | French (France) | `pt` | Portuguese |
| `de` | German | `fr-lu` | French (Luxembourg) | `pt-br` | Portuguese (Brazil) |
| `de-at` | German (Austria) | `ga` | Irish | `pt-pt` | Portuguese (Portugal) |
| `de-de` | German (Germany) | `hr` | Croatian | `ro` | Romanian |
| `el` | Greek | `hu` | Hungarian | `ru` | Russian |
| `el-cy` | Greek (Cyprus) | `id` | Indonesian | `sk` | Slovak |
| `el-gr` | Greek (Greece) | `it` | Italian | `sl` | Slovenian |
| `en` | English | `ja` | Japanese | `sv` | Swedish |
| `en-gb` | English (UK) | `ko` | Korean | `th` | Thai |
| `en-nz` | English (NZ) | `lt` | Lithuanian | `tr` | Turkish |
| `en-us` | English (US) | `lv` | Latvian | `uk` | Ukrainian |
| `es` | Spanish | `ms` | Malaysian | `vi` | Vietnamese |
| `es-es` | Spanish (Spain) | `mt` | Maltese | `zh` | Chinese |
| `es-mx` | Spanish (Mexico) | `nl` | Dutch | `zh-cn` | Chinese (Simplified) |
| `et` | Estonian | `nl-be` | Dutch (Belgium) | `zh-tw` | Chinese (Traditional) |
| `fi` | Finnish | `nl-nl` | Dutch (Netherlands) | | |
## W-Form in-form options (19)
| Code | Language | Code | Language |
| ------- | ---------------- | ------- | --------------------- |
| `de` | German | `nl` | Dutch |
| `en-us` | English (US) | `pl` | Polish |
| `es-mx` | Spanish (Mexico) | `pt-br` | Portuguese (Brazil) |
| `fr-ca` | French (Canada) | `ro` | Romanian |
| `id` | Indonesian | `ru` | Russian |
| `it` | Italian | `th` | Thai |
| `ja` | Japanese | `tr` | Turkish |
| `ko` | Korean | `vi` | Vietnamese |
| `ms` | Malaysian | `zh-cn` | Chinese (Simplified) |
| | | `zh-tw` | Chinese (Traditional) |
# Compatibility
`@taxbit/react-sdk` supports React `16` through `19` (declared as a peer dependency). TypeScript type definitions are bundled with the package — no separate `@types` install needed. They resolve under every `moduleResolution` setting, including `node16` / `nodenext` and CommonJS `require`, and type-check with `skipLibCheck: false`. For upgrade notes between versions, see the [Upgrade guide](https://apidocs.taxbit.com/docs/upgrade-guide).
# Sibling pages
* [How the SDK works](https://apidocs.taxbit.com/docs/how-the-sdk-works.md)
* [Questionnaire integration guide](https://apidocs.taxbit.com/docs/integration-guide.md)
* [Handling token expiration](https://apidocs.taxbit.com/docs/handling-token-expiration.md)
* [Customizing look and feel](https://apidocs.taxbit.com/docs/customizing-look-and-feel.md)
* [Curing integration guide](https://apidocs.taxbit.com/docs/curing-integration-guide.md)
* [Upgrade guide](https://apidocs.taxbit.com/docs/upgrade-guide.md)
* [Tax documentation FAQ](https://apidocs.taxbit.com/docs/tax-documentation-guide.md)