Concepts

The server decides the questions

The V0 API is hypermedia: each response says what you can do next (_links, _templates). Only the API root is hard-coded; the SDK follows everything else.

• Each response lists the outstanding questions only.
• Answering a question can reveal new ones (the trade question appears after the business owner and state answers) or retract dependants.
• The questionnaire is ready when the server offers a quotes link. That link is the only readiness signal.

So never hard-code the flow. Render what arrives. This lets products change their questions without breaking your integration.

You decide the UX

The SDK has no UI. The view-model gives you render-ready data (Screen, Field, QuoteCard); you draw it with your own design system. Unknown question types fall back to text, so a new server type never crashes your form.

Key by name, submit by field

Every question has a name (unique) and a field (the submit key, not unique: the same field can appear under two names).

• The session and view-model key everything by name. The session submits by field for you.
• The raw client’s answer() takes fields.

The API never echoes answers

Reading a questionnaire returns its outstanding questions, never the answers already given. So the client owns answer state:

• The session keeps every value locally and persists it through a StorageAdapter.
• After a reload, session.start() resumes the stored questionnaire with client.resume(id) and restores the answers from storage.
• If the stored questionnaire has expired (401, 403, 404 or 410), the session clears storage and starts fresh.

Use sessionStorageAdapter() in browsers. The default, memoryStorage(), is lost on reload.

Answers are PII

Answers are personal data.

• They are never in error messages, transport hooks or session events.
• Session events carry counts, durations and error names only, so you can send them to analytics safely.
• Stored answers are removed on handoff.

Don’t log state.values.

Errors are data

• A rejected answer comes back as a 200 with an entry in errors, not as an exception. The session puts it in state.errors; fieldState turns it into a message.
• Session actions never reject. Failures land in state: sync.status: "error", quotes.status: "failed", error: { action }. Read them from the screen, not from try/catch.
• The raw client throws typed errors, all extending SdkError. See Errors.

Quoting is asynchronous

Once ready, insurers are quoted in the background. The SDK polls the quoting monitor, honouring Retry-After, until the quote set settles (default timeout 2 minutes). If quoting fails, the server offers a retry: session.retryQuotes() or QuoteFailedError.retry().

The journey ends in a handoff

V0 has no purchase endpoints. You select a quote, then redirect the customer to the signed quote_comparison URL to buy. If every quote is referred or declined, nothing is selectable: call session.handOff() to send them there anyway.

Small by design

Each entry point has a gzip budget enforced in CI: core 8 KB, session 6 KB, view-model 6 KB. Import only the layers you use.