Props, hooks, types, status enums, callbacks, and CSS customization for @taxbit/react-sdk. For setup, see the Integration guide.

`<TaxbitQuestionnaire/>` 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 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'`	Controls how the SDK behaves when previously submitted data exists. `full` (default): walks through all screens with data pre-filled. `skipLock`: skips the form and shows a locked, read-only summary the account owner cannot change. `skipEdit`: skips the form and shows an editable summary for review and resubmission. See Adaptive mode.
`language`	`string`	No	`'en-us'` (W-FORM), `'en-gb'` (DPS, SELF-CERT)	Pre-selects the form language. See 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.
`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.
`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.
`region`	`'US' \| 'EU'`	No	`'US'`	Routes SDK API requests to the selected Taxbit region.
`dateFormat`	`'mdy' \| 'dmy' \| 'ymd'`	No	`'mdy'`	Order of date-of-birth select inputs when displayed.
`loadingComponent`	`ReactNode`	No	Text: "Retrieving interview status..."	Custom component displayed while the SDK fetches status from 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 object.
`onSubmit`	`(data: ClientTaxDocumentation) => void`	No	—	Called after the form passes client-side validation, before the API request completes.
`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 during submission. If omitted, the error is logged to the console and shown in the SDK's error alert — not rethrown.
`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.

`useTaxbit` hook

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.
`region`	`'US' \| 'EU'`	No	Regional server for API requests. Default `'US'`.
`proxyDomain`	`string`	No	Route requests through your own proxy.
`proxyHeaders`	`Record<string, string>`	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-data`).
`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.

Types

Progress

Passed to onProgress.

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.

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;
  };
};

Status enums

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.

QuestionnaireIssue

Found on wFormQuestionnaire.issues and selfCertification.issues.

type QuestionnaireIssue = {
  issueType: IssueType;
  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.

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-data`	On load — fetches prior data for pre-fill.
User submits the form	Posts form data to the submission endpoint	On a valid submit.
`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.

Stylesheets

The form is semantic HTML with taxbit- namespaced classes. Import one built-in stylesheet, then override classes in your own CSS.

Stylesheet	Description
`inline.css`	Full Taxbit default styling. Best starting point — also the reference for every available class name.
`basic.css`	Minimal structural styling; a good base when you want full control over visual design.
`minimal.css`	Bare minimum; use when your app's global styles should take over.

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).

`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)

React 16–19 · TypeScript 5.

<TaxbitQuestionnaire/> props