Walkthrough
One W-9, from the first request to the stored document.
One W-9, from the first request to the stored document.
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.
This walkthrough follows a US individual through a W-Form. The JSON is trimmed to what matters at each step. Responses are wrapped in data.
1. Open the form
When the form opens, your UI sends one request before drawing anything but a loading state. It names the questionnaire and carries anything you already know:
POST /v1/tax-documentation/validations
Authorization: Bearer <account owner token>
taxbit-client: acme-onboarding/1.4.0
Content-Type: application/json
{
"questionnaire": "W-FORM",
"locale": "en-us",
"settings": {},
"advancing": false,
"checks": []
}Taxbit answers with the whole form as it stands:
{
"data": {
"complete": false,
"document": {},
"fields": [
{
"key": "account_holder.is_us_person",
"ui_type": "radio",
"phase": "classification",
"step": "accountHolderClassification",
"text": { "label": "Are you a U.S. person?" },
"options": [ /* Yes, No */ ],
"on_change": ["shape", "hide_errors"],
"required": true,
"errors": [ /* a hidden "required" error */ ]
}
],
"errors": [ /* … */ ],
"checks": [],
"page": "accountHolderClassification",
"pages": [ /* … */ ]
}
}If Taxbit already holds documentation for this person, it's merged in here: document comes back filled, and a complete, unchanged form opens on the review page. Your UI takes document as its answers.
2. The user answers, and the form changes shape
Each field says when to call again in on_change:
shape: call right away. The answer changes which questions exist.feedback: call after the user pauses typing for 350 ms. It's a live format check, like a TIN.- Neither: don't call. The answer rides along on the next request.
The user says they're a US person. That's a shape field, so the UI sends the answers so far:
{
"questionnaire": "W-FORM",
"account_holder": { "is_us_person": true },
"settings": {},
"locale": "en-us",
"advancing": false,
"checks": [],
"page": "accountHolderClassification",
"last_changed": "account_holder.is_us_person"
}The response now asks the W-9 questions: how the account is taxed, name, address and TIN. Had they picked Limited liability company instead, the next response would add the LLC tax classification question and relabel the TIN as an EIN. Your UI draws whatever arrives. It never decides which questions exist.
3. Show errors at the right moment
Every response carries every error, including errors on questions the user hasn't reached yet. Your UI decides when to show them: a blank required field once the user tries to continue, an invalid value like an 8-digit TIN as soon as it's entered. Each error has a stable code and ready-to-show text.
4. Move on
When the user presses Next, send the same request with advancing: true and next: true. External checks run only on these requests. That's the GIIN check against the IRS FFI list on any W-8 that asks for a GIIN, and, with real-time TIN validation on, the IRS name and TIN match on a W-9. Their results come back in checks, which your UI sends back unchanged on every request after.
5. Submit
On the review page, the user presses Submit. Your UI sends one more request with advancing: true. When the answers are complete, the response says so and carries the signed document:
{
"data": {
"complete": true,
"errors": [],
"submission": { /* the signed W-9 */ }
}
}An individual never answers a signature question: pressing Submit is the act of signing, and Taxbit derives the signature from their name.
Your UI posts submission, unchanged, to the submissions endpoint. Taxbit stores it and returns a receipt with the document's id. The form now appears on the account owner's tax documentation status and in the Taxbit dashboard.
Next steps
The developer guide covers every rule in detail, including concurrency, pre-filling and failures.
Updated 36 minutes ago
