Skip to main content
POST
Plan the next question for market rater versions

Authorizations

​
Authorization
string
header
required

Effective API key. Send Authorization: Bearer sk-eai-...

Body

application/json
​
programs
object[]
required

The programs, each at the version this server rates with or at a pinned version. Each reads only the paths its own contract declares.

Required array length: 1 - 10 elements
​
answers
object
required

Every answer so far, keyed by root record.

​
skipped
string[]

Paths the person put off, in order: each the path of the card put off, as the plan showed it. A follow-up asked in its yes/no’s place (a card with noneAnswer) is put off by its own path; the yes/no’s path (noneAnswer.gate) puts off the same card.

​
after
string | null

The path answered last.

​
sections
string[]

The order the host shows sections in.

​
offered
string[]

Document kinds already offered.

​
confirmed
string[]

The choices paths the person has confirmed. Keep each with the value confirmed and drop one whose value, or whose set of choices, changed.

​
previous
object[]

Each program’s status from the previous call, and its state’s kind if you kept it. changes lists the programs whose status, or state, differs now.

Maximum array length: 10
​
asOf
string<date>

The date answers are as of, YYYY-MM-DD. It fills look-back windows such as “since March 2016”. No rater reads the clock.

​
priceAt
string

Where a program’s price is in its outputs, such as Policy.premium. With it, each program that misses no answer comes back with an estimate: its price with its own usual and typical answers for the questions not yet answered, and the range around it.

Maximum string length: 200
Pattern: ^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$
​
termAt
string

Where the policy term, in months, is in a program’s outputs, such as Policy.term_months. With it and priceAt, each estimate says the term its amounts are for (termMonths), so estimates of different terms can be compared a month.

Maximum string length: 200
Pattern: ^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$
​
fills
object[]

What the host fills from an answer, such as a car’s year and make from its VIN. A question that fills others is asked before them.

Maximum array length: 20
​
choices
object

What the person buys, by path: a limit, a deductible, a term. Each program is rated at its nearest step, by the shape its contract gives the choice (x-shape): a limit or a per-day amount rounds up in every part, a limit pair up to the smallest pair at least both parts, a deductible down to the largest step at most it, and an included, tier or term choice must match. A choice a program cannot price is not_offered for it, and that program rates its default; saying none (no to a yes/no, or leaving out a choice that may be left out) is priced as asked by a program with nothing at that path. When a program does not sell a choice as asked, task.differences says so and overrides takes the person’s pick. A choice at a path no program in the basket sells is left out and named in issues (CHOICE_NOT_SOLD); it never fails the request.

​
overrides
object[]

The person’s picks for programs that do not sell a choice as asked: each program is priced at its pick in place of its nearest step. Answer each of task.differences with one pick per program (accepting the suggestion is a pick equal to suggested). A pick is ignored, so its choice is asked again, once the choice is no longer asked, or when it names a program outside the basket or a step its program does not sell (a new version may drop one).

Maximum array length: 200
​
displayNames
object

The names the host keeps for list items, by the item’s path (Policy.drivers[1]: “Harshita”), as a card’s itemName asks them. Never sent to a program: names words each item with its name, such as “Harshita (your spouse)”.

​
context
object

Values the host holds that are no answers, by key, such as where the person lives (zip). A fact whose usual answer is one of them (its contract’s x-common-from names the key) is not asked: it is listed in assumed with the value, and every program is rated with it. The plan never reads what a key means.

​
check
string[]

Answered paths to check against the choices the other answers narrow them to: send the answers a save gives, not every stored answer. Some questions take only the answers the earlier ones leave (a car’s model, by its year and make: a card with choices and no more), and no contract lists those, so such an answer is checked only when named here. Each program that narrows it is rated once more with that answer left out, and an answer none of them lists comes back in issues as NOT_A_CHOICE, with expected.choices and the candidates that may be meant. A path that is not such a question costs nothing.

Maximum array length: 50

A path in answers, such as Policy.vehicles[0].collision.deductible.

Maximum string length: 500
Pattern: ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$
​
again
string[]

Paths the person asked to answer again. To read an answered question as it would be asked now, leave its answer out of answers and name its path here: its card comes back among questions whatever it waits on (the answer that would fill it, such as a car’s VIN, or the question it follows), with the answers the other answers leave it. Nothing is saved by a plan.

Maximum array length: 20

A path in answers, such as Policy.vehicles[0].collision.deductible.

Maximum string length: 500
Pattern: ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$

Response

The next question and each version’s status.

​
asOf
string | null
required

The request’s asOf.

​
answers
object
required

The answers as Effective read them: a full VIN given at a car’s vin_pattern is cut down to its pattern, with what its decode filled (the car’s vpic_* answers). Send these back on the next call.

​
implied
object[]
required

The answers other answers imply, rated and planned with but not in answers: a new list item’s key (the list’s largest plus one, Policy.vehicles[1].vehicle_id: 2), and the yes/no a follow-up asked in its place answers (a card with noneAnswer), where that yes/no is not answered itself: yes when the follow-up has a value (a VIN given answers vin_known true), no when it is saved as null, which says none, also beside a stored yes; and, on the first item of a list whose card has you, that field with that value when the item is sent without it: the first item is the person answering. Store them over what you hold; you never need to write them.

​
task
object
required

The one thing the person does next. confirm_choices while a choice is not confirmed or a difference is open, as soon as every list that gives a choice its record is closed (a car’s deductible needs the cars to be all in), though questions may still be open: what is chosen can open more questions, so the choices come before them, and questions keeps listing what comes after. Otherwise answer_screen, the first screen with a question that is not put off; with none left, confirm_choices for whatever is still to choose; else review_results, each program where it stands. Follow the task, not the length of questions: adding a list item later asks its own choices once its list is closed again.

​
open
object[]
required

Every open fact once, with the programs that need it: group programs (two of one insurer) by the union of their paths so a shared fact counts once.

​
next
object
required

The next question card, the first of questions, or null when every program is settled. While task is confirm_choices it is the question that comes after the choices: show what task says.

​
questions
object[]
required

Every open card, in asking order.

​
answered
object[]
required

Every answered question as it reads now, in the contracts’ order. questions holds only the open cards, and a question is worded from the answers of its record, so the words an answer was asked with go stale: “What year is car 1?” is “What year is the 2020 Toyota RAV4?” once the car has its make. Show an answer under these words, not the ones kept from when it was asked. Holds each answer at a question the contracts word (an answer no contract asks in words, such as what a decode filled, is not a question); never a choice (see choices) or a list item’s key.

​
sections
string[]
required

Every section of the basket in the order the plan asks them: the ones sent as sections, then the rest in the order the contracts declare them. A section that holds only choices stands where the plan asks the choices, whatever place it was sent at: after the section of the last list that holds a choice (the cars), or first when no choice is under a list. A card’s section and a screen’s are among these, so a host that sends no sections can list them from here, and one that counts steps counts these.

​
ready
string[]
required

The programs that are settled, as programId@version.

​
changes
object[]
required

Each program whose status differs from previous, and, where previous gave its state, each whose state’s kind differs: a program rated before its choices were confirmed has the status priced throughout, and is listed when its state becomes priced. Why a program stands where it does is in its state.

​
choices
object[]
required

What the person buys across the basket, asked once rather than as cards.

​
names
object
required

Each list item’s name by its path, such as Policy.vehicles[0]: “the 2020 Toyota RAV4”.

​
issues
object[]
required

Answers in answers or choices that the basket’s contracts cannot read as sent, answers named in check that are none of the choices the other answers narrow them to (NOT_A_CHOICE, as for an answer outside a listed enum), (NOT_SOLD) picks in overrides of a step their program does not sell, which are ignored, and (CHOICE_NOT_SOLD) entries of choices at a path no version in the basket sells, which are left out with their confirmed and overrides entries while the rest is planned. Correct each and plan again; stop sending a CHOICE_NOT_SOLD choice.

​
screens
object[]
required

The questions packed into what a host shows at once; next is the first’s first.

​
progress
object
required

How much is left.

​
programs
object[]
required
​
lists
object[]

Each open list’s add action (its more card: “Any other cars?”, with addLabel and items), whether or not a screen holds it. “Is that all of them” is never a screen by itself: show it with the list’s items and send <list>_complete: true when the person moves on.

​
assumed
object[]

What the plan assumes instead of asking: a usual answer every program that asks it declares the same and asks on no checklist (source: usual), a value read from another answer (such as a decode), or one given in context. Every program is rated with these, so a price is exact for the stated assumptions: list them and let the person change one (card is its question). Never save one as the person’s answer; answering the path replaces it.

​
estimateWaitsOn
object

For each open program (programId@version), the paths an estimate of it still waits on: its open questions it asks first or gives no usual answer, and its choices not yet confirmed. An empty list: an estimate of that program can be shown.

​
labels
object

Each list item’s own label by its path, as its answers give it, such as “your spouse” or “car 2”, whatever name was sent for it in displayNames. names holds the name to show.