Logic API developer guide
How to build a client on the Logic API.
How to build a client on the Logic API. The client spec is the complete, normative contract; this guide covers what you need to plan an integration.
BetaThe Logic API is live and ready to use. Every Taxbit client can call it today, with no sign-up: the client spec and validation endpoints are in the API reference. The beta label means the shape of its responses may change before general availability.
The rule behind everything
Taxbit owns the questionnaire. Which fields exist, their order, which are required, what counts as a valid answer and whether the form is complete all arrive in each response. Your client draws what arrives. It doesn't keep its own copy of any rule, infer a rule from a field's name, or decide on its own that a form is ready to submit.
That one rule is what lets a single client handle every questionnaire. A W-8BEN-E asks about FATCA classification and a W-9 doesn't, but both arrive as the same kinds of fields.
Endpoints
| Endpoint | What it does |
|---|---|
POST /v1/tax-documentation/validations | Takes the answers so far and returns the form for them. Read-only and stateless. |
POST /v1/tax-documentation/submissions | Stores a finished, signed document. |
GET /v1/tax-documentation/client-spec | Returns the client spec: protocol, vocabulary, example exchanges and conformance script. |
Requests go to https://api.multi1.enterprise.taxbit.com. Successful responses wrap the body in data.
Send taxbit-client: <your app>/<version> on every request. Taxbit records it as the stored document's source.
Authentication
Validations and submissions take an account owner token: one person, one token, no access to anyone else's documents. It's the same token the React SDK uses.
- Your server requests an account owner token with your client ID and secret and the
idof the person filling in the form. - Your client sends that token on its requests, or sends its requests through your server.
An account owner token lasts an hour. The client spec endpoint is the exception: it takes a tenant token, not an account owner token. Neither token is accepted where the other belongs.
Keep your secret on your serverYour client secret never leaves your server, and the account owner token never ships in code delivered to a browser. It reaches your client at runtime from your server.
The request
The answers are the request. Form answers sit at the top level, in snake_case, beside a few reserved members:
| Member | |
|---|---|
questionnaire | Required. W-FORM, W-9, W-8, W-8BEN, W-8BEN-E, W-8IMY, SELF-CERT or DPS. |
settings | Which questions are asked. The same on every request in a session. |
locale | The preferred language. Every text in the response comes back in it. |
advancing | true only when the user presses Next or Submit. |
checks | The checks from the previous response, sent back unchanged. |
revealed | The revealed from the previous response, sent back unchanged, when it carried one. |
showing | With advancing: the keys of what the user moved on from. Required for a modal; see Submitting. |
reveal | The review row an Edit opens, when its edit says so. |
page, pages_before, pages_left, last_changed, next | Where the user is, so Taxbit keeps them in place as the form changes shape. |
| everything else | The document as answered so far. |
Settings
| Setting | What it does |
|---|---|
fatca | Ask the FATCA questions. |
treaty_claims | Ask the treaty-claim questions. Needs types_of_income. |
types_of_income | The kinds of income the treaty claims cover. |
e_delivery_consent | Ask for consent to electronic delivery when the user signs a W-form. |
date_format | The order a date's parts are asked in: mdy, dmy or ymd. Answers are always sent as MM/DD/YYYY. |
minimum_age | The youngest age a date of birth can give. |
real_time_tin_validation | Match a W-9's name and TIN with the IRS while the user answers. Off unless true. |
prepopulate_with_saved_data | Start from the documentation Taxbit already holds. On unless false. |
An invalid combination, such as treaty_claims without types_of_income, fails with a 400.
The response
| Member | What it is |
|---|---|
complete | Whether the document may be submitted. Gate Submit on this, never on errors being empty. |
fields | The questionnaire as a tree of fields. |
errors | The errors over what this response asks, each with a stable code and ready-to-show text. |
document | The answers as Taxbit reads them, normalised. |
checks | Every external check result so far. Send it back. |
cleared | Answers this request reset. Drop them. |
modal | Something that needs the user's attention apart from the form, such as a TIN mismatch. |
submission | The signed document, present only when complete. |
phases, steps, units, pages, page | How the form is grouped and paged, and where the user is. |
text, buttons, statuses, locale, locales | Screen copy, and the languages offered. |
A field
Each field carries its key (the path its answer takes in the document), a ui_type that says what to draw, its text (label, sublabel), options, required, disabled, its errors, and on_change, which says when to call again. Some also carry a status note (a passive hint, not an error), a mask for formatting as the user types, and an autocomplete token for the input.
ui_types fall into three groups:
- Controls such as
textInput,select,radio,checkbox,dateOfEventandphoneNumber - Structure such as
section,field_rowandarray(a repeatable list, like controlling persons) - Read-only such as
callout,display(a row on the review page) andtext
Treat an unrecognized ui_type as an error rather than skipping it, so no question silently drops out of the form. Always use the options that arrive with a field; a country or state list held locally goes stale.
The request cycle
Your client holds the answers, the checks table and where the user is, and sends them on every request.
- Open. Validate once before drawing anything but a loading state. Take the first response's
documentas your answers: that's where saved documentation arrives. - On change. Follow the field's
on_change.shapecalls right away;feedbackcalls after 350 ms with no typing; anything else rides the next request. Never call on every keystroke. - Advance. On Next and Submit, send
advancing: true. The IRS TIN match and the FFI GIIN check run only on these requests. - Apply each response. Keep the new
checks, drop theclearedanswers, and replace what's on screen.
Responses can arrive out of order. Number your requests, apply only the newest response, and cancel the in-flight background request when you start another.
Showing errors
Every response carries every error, including errors on questions the user hasn't reached. When they appear is your client's choice. The usual pattern, and Taxbit's own: show a page's missing-answer errors once the user presses Next, show format errors as soon as the user pauses typing, and show everything on Submit. Branch on an error's code if you need to; it doesn't change with the language. Show the text of any code you don't recognize, because codes are added as rules are.
Submitting
- Send one validate request with
advancing: true. - If
completeis false, show the errors and stop. - Post
submissionto/v1/tax-documentation/submissionsunchanged. Don't edit, re-sign or re-key it. - Treat a response with no document
idas a failure.
Don't collect a signature from individuals: pressing Submit is the act of signing. Entities are asked for a signature as an ordinary field. With real-time TIN validation on, a TIN mismatch arrives in modal and the user must acknowledge it before moving on. The request that moves on from the modal must carry the modal's key in showing; without it, the document stays complete and submits with the mismatch unacknowledged.
Failures
When a request fails, keep the last good response on screen, show that the form is out of date, and keep the user's answers. Don't clear answers or change the page. An aborted request isn't a failure.
Accessibility
A client you build doesn't inherit Taxbit's accessibility work. At minimum, tie every visible error to its input so screen readers announce it, mark required fields in code, move focus to the first field in error when Next or Submit is refused, and keep the reading order the same as fields.
Check your client
The client spec includes conformance.mjs, which checks your client by watching the requests it makes. Point your client at its wrapped caller, use the form, and it reports every rule your traffic broke and every rule it never exercised. It doesn't need to know how your UI is built.
Not in the Logic API yet
Curing a rejected W-8 and the document download screen aren't part of the Logic API beta.
Updated 36 minutes ago
