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.

🚧

Beta

The 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

EndpointWhat it does
POST /v1/tax-documentation/validationsTakes the answers so far and returns the form for them. Read-only and stateless.
POST /v1/tax-documentation/submissionsStores a finished, signed document.
GET /v1/tax-documentation/client-specReturns 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.

  1. Your server requests an account owner token with your client ID and secret and the id of the person filling in the form.
  2. 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 server

Your 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
questionnaireRequired. W-FORM, W-9, W-8, W-8BEN, W-8BEN-E, W-8IMY, SELF-CERT or DPS.
settingsWhich questions are asked. The same on every request in a session.
localeThe preferred language. Every text in the response comes back in it.
advancingtrue only when the user presses Next or Submit.
checksThe checks from the previous response, sent back unchanged.
revealedThe revealed from the previous response, sent back unchanged, when it carried one.
showingWith advancing: the keys of what the user moved on from. Required for a modal; see Submitting.
revealThe review row an Edit opens, when its edit says so.
page, pages_before, pages_left, last_changed, nextWhere the user is, so Taxbit keeps them in place as the form changes shape.
everything elseThe document as answered so far.

Settings

SettingWhat it does
fatcaAsk the FATCA questions.
treaty_claimsAsk the treaty-claim questions. Needs types_of_income.
types_of_incomeThe kinds of income the treaty claims cover.
e_delivery_consentAsk for consent to electronic delivery when the user signs a W-form.
date_formatThe order a date's parts are asked in: mdy, dmy or ymd. Answers are always sent as MM/DD/YYYY.
minimum_ageThe youngest age a date of birth can give.
real_time_tin_validationMatch a W-9's name and TIN with the IRS while the user answers. Off unless true.
prepopulate_with_saved_dataStart 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

MemberWhat it is
completeWhether the document may be submitted. Gate Submit on this, never on errors being empty.
fieldsThe questionnaire as a tree of fields.
errorsThe errors over what this response asks, each with a stable code and ready-to-show text.
documentThe answers as Taxbit reads them, normalised.
checksEvery external check result so far. Send it back.
clearedAnswers this request reset. Drop them.
modalSomething that needs the user's attention apart from the form, such as a TIN mismatch.
submissionThe signed document, present only when complete.
phases, steps, units, pages, pageHow the form is grouped and paged, and where the user is.
text, buttons, statuses, locale, localesScreen 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, dateOfEvent and phoneNumber
  • Structure such as section, field_row and array (a repeatable list, like controlling persons)
  • Read-only such as callout, display (a row on the review page) and text

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.

  1. Open. Validate once before drawing anything but a loading state. Take the first response's document as your answers: that's where saved documentation arrives.
  2. On change. Follow the field's on_change. shape calls right away; feedback calls after 350 ms with no typing; anything else rides the next request. Never call on every keystroke.
  3. Advance. On Next and Submit, send advancing: true. The IRS TIN match and the FFI GIIN check run only on these requests.
  4. Apply each response. Keep the new checks, drop the cleared answers, 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

  1. Send one validate request with advancing: true.
  2. If complete is false, show the errors and stop.
  3. Post submission to /v1/tax-documentation/submissions unchanged. Don't edit, re-sign or re-key it.
  4. Treat a response with no document id as 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.