Questionnaire

A Questionnaire is an immutable snapshot. Every call returns a new snapshot; the old one never changes.

let q = await client.start('cyber');
q = await q.answer({ 'US state': 'Ohio' });

Reference

Fields

• id: the questionnaire id. Store it to resume later.
• questions: the outstanding questions, each { field, name, prompt, type, required, options, search?, rules, ... }.
• sections: ordered { id, title? } groups. [] when the server sends none.
• errors: validation failures for the last answers, as data.
• ready: true once the server offers quotes. Narrows the type: only a ready snapshot has quotes.
• recommendations: products to quote, on a recommendation questionnaire. See below.
• questionnaire: { name, version }.
• raw: the response body, untouched.

---

q.answer(...)

Sends answers in one PATCH. Three forms:

await q.answer('US state', 'Ohio');
await q.answer({ 'US state': 'Ohio', 'Business owner': 'yes' });
await q.answer([{ field: 'US state', value: 'Ohio' }]);

• Keys are question fields, not names.
• Values are wire values: dates YYYY-MM-DD, phones E.164 (+12165550123), currency as plain numbers. The session’s encode converts UI values for you.

Returns Promise<Questionnaire>: the snapshot from this call’s response.

Caveats: calls on the same questionnaire are queued and sent one at a time, in order. A rejected value is not an exception: check errors.

---

q.refresh()

Re-reads the questionnaire. Returns Promise<Questionnaire>.

---

q.searchTrade(text)

Searches trades through the trade question’s search template.

const { results } = await q.searchTrade('handyman');
q = await q.answer('Primary trade', results[0].value);

Returns Promise<{ results: TradeResult[]; searchId }>. Each result has value, label, definition? and blocked?. Submit value; never submit a blocked trade.

---

recommendations

On a recommendation questionnaire, once trade and US state are answered: { vertical, title, start(options?) }[]. start() returns a quoting questionnaire seeded with the answers carried over.

Usage

Answer until ready

while (!q.ready) {
  const values = collectAnswers(q.questions); // your UI
  q = await q.answer(values);
  if (q.errors.length) showErrors(q.errors);
}
const quoteSet = await q.quotes.wait();

Troubleshooting

A question I answered came back

Changing an answer can retract dependent questions, and the server asks for them again. Render q.questions after every response.

ValidationError (422)

You sent a field the server doesn’t know, or a malformed body. Check you’re using field, not name.