> ## Documentation Index > Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Plan the next question for market rater versions > Name the market rater versions a household may be rated by, send every answer so far, and get the next question and each version’s status. A version’s status is `priced`, `declined`, `invalid` or `open`, as for [rating with `allowMissing`](/api-reference/market-raters/rate-a-submission-with-a-market-rater-version), or `failed` when the version could not be read (its engine or its input contract) or its rater could not rate the answers: one version’s failure is its own, and the others are still rated and planned, so the response is 200 even when every version failed. The status is the rater’s word for the answers and choices it was rated on; `state` says where the version stands for the person. Name each rater by `programId` and leave `version` out: it is read at the version this server rates with, the newest published version its rating engine can load, and `programs[].version` in the response names it. Keep that `version` and `bundleId` with a price. Do not pick a version from [List market rater versions](/api-reference/market-raters/list-market-rater-versions) yourself: its newest may be one that waits for a server release. Send a `version` only to pin one; a pinned version this server cannot load fails the request with 409 `version_not_loadable`. Every version is in one `state`, and every state but `priced` says the way out: `needs` lists the questions to answer and the choices to make, each with the `error` when the version refused what was given; `declined` gives the reason and the answers to `change`; `failed` gives the reason, and the way out is to try again. Nothing is asked twice without an `error`. A version is `priced` in `state` only once every choice it prices is confirmed: until then it `needs` those choices, even when its rater already returned a result. Effective stores nothing between calls: each call carries all answers, so the same request always returns the same question, and a retry is safe. One set of answers serves the whole basket, and each version reads only the paths its own input contract declares. `next` is a card the person answers: its `kind` and `format` say which input to show, and its `path` says where the answer goes in `answers`. It is `null` once every version is priced or declined. `questions` holds every open card in asking order, each with its `screen`, the record it belongs to: show a screen's cards together. Send each version's status from the previous call as `previous`: `changes` then names each version whose status changed, with the refused answer for a decline. Send `asOf` to fill look-back windows such as "since March 2016". Send a car's full VIN at its `vin_pattern`: Effective decodes it, fills the car's `vpic_*` answers and keeps only the pattern, and returns the answers as it read them in `answers`. What the VIN suggests, such as the car's year, make, model, drive, fuel and body, rides on those questions' cards as `suggested` with `source` `vin_decode`: show them together and let the person confirm or correct them. A client with its own decode may send the `vpic_*` answers instead. Send `fills` for what else you fill from an answer: a question that fills others is asked before them. A card with `noneAnswer` stands in for a yes/no: "What's the VIN?" with "I don't have it" beside it. Any answer there says yes; the none answer, or `null` saved at the card's `path`, says no. `implied` returns that yes/no, so you never write it. `null` is an answer wherever a card is `nullable`: nothing asks there again. To put a card off, send the `path` it shows in `skipped`; it comes back last, marked `revisit`. Coverage is chosen, not asked: `choices` in the response lists each limit, deductible or term the basket prices, with every program's steps. The task asks for it (`confirm_choices`) as soon as the lists its choices belong to are closed, such as the cars, and before the questions still open, because a version can need more answers for what was chosen; those questions then come with the rest, and the results follow the last question. Send the person's choices as `choices`, by path. Each version is rated at its own nearest step, by the shape its contract gives the choice: a limit up, a limit pair up as one pair, a deductible down. It reports in its `choices` what it priced. When some versions do not sell a choice as asked, `task.differences` lists them with the steps they do offer: ask the person once, and send the pick as `overrides`. `issues` lists answers or choices the versions' contracts cannot read as sent, each with its `path`, a `code` and, where known, what is `expected` and `candidates` that may be meant. Correct them and plan again. A choice at a path no version in the basket sells never fails the request: it is left out, with its `confirmed` and `overrides` entries, the rest is planned, and `issues` names it with the code `CHOICE_NOT_SOLD`. This happens when a stored choice belongs to a version that has left the basket, or to an older version of one that no longer has it; stop sending it. Saying none to a choice (leaving it out where it may be, or no to a yes/no) is priced as asked by a version that has nothing at that path. Needs access to rate every named version and your `raters:run` permission. Rating changes nothing, so the request is safe to repeat. ## OpenAPI ````yaml /openapi.json post /insurance/rating-programs/plan openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://api.effectiveai.app/api/v2 description: Production security: - bearerAuth: [] paths: /insurance/rating-programs/plan: post: tags: - Market raters summary: Plan the next question for market rater versions description: >- Name the market rater versions a household may be rated by, send every answer so far, and get the next question and each version’s status. A version’s status is `priced`, `declined`, `invalid` or `open`, as for [rating with `allowMissing`](/api-reference/market-raters/rate-a-submission-with-a-market-rater-version), or `failed` when the version could not be read (its engine or its input contract) or its rater could not rate the answers: one version’s failure is its own, and the others are still rated and planned, so the response is 200 even when every version failed. The status is the rater’s word for the answers and choices it was rated on; `state` says where the version stands for the person. Name each rater by `programId` and leave `version` out: it is read at the version this server rates with, the newest published version its rating engine can load, and `programs[].version` in the response names it. Keep that `version` and `bundleId` with a price. Do not pick a version from [List market rater versions](/api-reference/market-raters/list-market-rater-versions) yourself: its newest may be one that waits for a server release. Send a `version` only to pin one; a pinned version this server cannot load fails the request with 409 `version_not_loadable`. Every version is in one `state`, and every state but `priced` says the way out: `needs` lists the questions to answer and the choices to make, each with the `error` when the version refused what was given; `declined` gives the reason and the answers to `change`; `failed` gives the reason, and the way out is to try again. Nothing is asked twice without an `error`. A version is `priced` in `state` only once every choice it prices is confirmed: until then it `needs` those choices, even when its rater already returned a result. Effective stores nothing between calls: each call carries all answers, so the same request always returns the same question, and a retry is safe. One set of answers serves the whole basket, and each version reads only the paths its own input contract declares. `next` is a card the person answers: its `kind` and `format` say which input to show, and its `path` says where the answer goes in `answers`. It is `null` once every version is priced or declined. `questions` holds every open card in asking order, each with its `screen`, the record it belongs to: show a screen's cards together. Send each version's status from the previous call as `previous`: `changes` then names each version whose status changed, with the refused answer for a decline. Send `asOf` to fill look-back windows such as "since March 2016". Send a car's full VIN at its `vin_pattern`: Effective decodes it, fills the car's `vpic_*` answers and keeps only the pattern, and returns the answers as it read them in `answers`. What the VIN suggests, such as the car's year, make, model, drive, fuel and body, rides on those questions' cards as `suggested` with `source` `vin_decode`: show them together and let the person confirm or correct them. A client with its own decode may send the `vpic_*` answers instead. Send `fills` for what else you fill from an answer: a question that fills others is asked before them. A card with `noneAnswer` stands in for a yes/no: "What's the VIN?" with "I don't have it" beside it. Any answer there says yes; the none answer, or `null` saved at the card's `path`, says no. `implied` returns that yes/no, so you never write it. `null` is an answer wherever a card is `nullable`: nothing asks there again. To put a card off, send the `path` it shows in `skipped`; it comes back last, marked `revisit`. Coverage is chosen, not asked: `choices` in the response lists each limit, deductible or term the basket prices, with every program's steps. The task asks for it (`confirm_choices`) as soon as the lists its choices belong to are closed, such as the cars, and before the questions still open, because a version can need more answers for what was chosen; those questions then come with the rest, and the results follow the last question. Send the person's choices as `choices`, by path. Each version is rated at its own nearest step, by the shape its contract gives the choice: a limit up, a limit pair up as one pair, a deductible down. It reports in its `choices` what it priced. When some versions do not sell a choice as asked, `task.differences` lists them with the steps they do offer: ask the person once, and send the pick as `overrides`. `issues` lists answers or choices the versions' contracts cannot read as sent, each with its `path`, a `code` and, where known, what is `expected` and `candidates` that may be meant. Correct them and plan again. A choice at a path no version in the basket sells never fails the request: it is left out, with its `confirmed` and `overrides` entries, the rest is planned, and `issues` names it with the code `CHOICE_NOT_SOLD`. This happens when a stored choice belongs to a version that has left the basket, or to an older version of one that no longer has it; stop sending it. Saying none to a choice (leaving it out where it may be, or no to a yes/no) is priced as asked by a version that has nothing at that path. Needs access to rate every named version and your `raters:run` permission. Rating changes nothing, so the request is safe to repeat. operationId: planRatingProgramQuestions requestBody: required: true content: application/json: schema: type: object properties: programs: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true description: >- Leave it out to read the program at the version this server rates with: the newest published version its rating engine can load. The response names it. Send a version only to pin one. title: type: string maxLength: 100 description: >- How the host names this program to the person, such as `GEICO`. Defaults to the program’s name. required: - programId additionalProperties: false minItems: 1 maxItems: 10 description: >- The programs, each at the version this server rates with or at a pinned version. Each reads only the paths its own contract declares. answers: type: object additionalProperties: nullable: true description: Every answer so far, keyed by root record. skipped: type: array items: type: string default: [] description: >- 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: type: string nullable: true default: null description: The path answered last. sections: type: array items: type: string default: [] description: The order the host shows sections in. offered: type: array items: type: string default: [] description: Document kinds already offered. confirmed: type: array items: type: string default: [] description: >- 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: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true description: Leave it out for a program sent without a version. status: type: string enum: - priced - declined - invalid - open - failed description: >- `failed`: the program could not be read or rated. The other programs plan on. state: type: string enum: - priced - needs - declined - failed description: >- The `state.kind` the program had in the previous call, if you kept it. `changes` then also lists a program whose state differs though its status does not. required: - programId - status additionalProperties: false maxItems: 10 default: [] description: >- 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. asOf: type: string format: date description: >- 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: type: string maxLength: 200 pattern: ^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$ description: >- 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. termAt: type: string maxLength: 200 pattern: ^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$ description: >- 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. fills: type: array items: type: object properties: source: type: string maxLength: 100 description: The host’s name for where the values come from. from: type: string maxLength: 500 description: >- The answered path, `[*]` for any list item: `Policy.vehicles[*].vin`. fills: type: array items: type: string maxLength: 100 maxItems: 50 description: The fields of that record it fills. required: - source - from - fills additionalProperties: false maxItems: 20 default: [] description: >- 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. choices: type: object additionalProperties: nullable: true default: {} description: >- 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: type: array items: type: object properties: programId: type: string description: A program of the basket. path: type: string maxLength: 500 pattern: >- ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$ description: The choice’s path, as in `choices`. asked: nullable: true description: >- The choice this pick answers, as sent in `choices`. A pick whose `asked` is no longer the choice is ignored, so a changed choice is asked again. value: nullable: true description: >- One of the steps this program offers at `path` (`choices[].steps[].programIds`), such as one of a difference’s `options`. required: - programId - path additionalProperties: false maxItems: 200 default: [] description: >- 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). displayNames: type: object additionalProperties: type: string maxLength: 30 default: {} description: >- 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: type: object additionalProperties: anyOf: - type: string maxLength: 200 - type: number - type: boolean default: {} description: >- 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: type: array items: type: string maxLength: 500 pattern: >- ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$ description: >- A path in `answers`, such as `Policy.vehicles[0].collision.deductible`. maxItems: 50 default: [] description: >- 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. again: type: array items: type: string maxLength: 500 pattern: >- ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$ description: >- A path in `answers`, such as `Policy.vehicles[0].collision.deductible`. maxItems: 20 default: [] description: >- 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. required: - programs - answers additionalProperties: false responses: '200': description: The next question and each version’s status. content: application/json: schema: $ref: '#/components/schemas/V2RatingProgramPlan' '400': description: Invalid request or cursor. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: >- Your organization’s access to the rater, or your permission, is missing. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: The rater, version or package is not found. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '409': description: >- version_not_loadable: this server’s rating engine cannot load the version; it was built for another release of the engine. Leave the version out to use the newest version this server loads; with no version named, none of the newest loads. conflict: the engine that serves this version differs from the engine it records. Retry later; if it persists, contact Effective. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '413': description: The inputs exceed 1 MiB. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: The request body is not application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '422': description: >- invalid_inputs or business_rejection: violations lists each failed constraint. evaluation_failed: the engine could not rate the inputs. content: application/json: example: code: business_rejection error: The program doesn't cover rideshare use. businessCode: RIDESHARE violations: - code: RIDESHARE message: The program doesn't cover rideshare use. path: Policy.vehicles[0].rideshare value: true constraint: 'rideshare: where not self' cite: manual:anchor "eligibility" violationsTruncated: false requestId: 1793385750835-0 schema: $ref: '#/components/schemas/V2CodedError' '429': description: Too many requests, or no rating capacity. Retry after Retry-After. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: Unexpected failure. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: A dependency is unavailable. Retry after Retry-After. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2RatingProgramPlan: type: object properties: asOf: type: string nullable: true description: The request’s `asOf`. answers: type: object additionalProperties: nullable: true description: >- 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: type: array items: type: object properties: path: type: string value: nullable: true required: - path description: >- 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: oneOf: - type: object properties: kind: type: string enum: - answer_screen screen: type: object properties: id: type: string kind: type: string name: type: string section: type: string description: As `screens[].section`. cards: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' required: - id - kind - cards required: - kind - screen additionalProperties: false - type: object properties: kind: type: string enum: - confirm_choices unconfirmed: type: array items: type: string description: The `choices` paths not yet confirmed. defaulted: type: array items: type: string description: >- Among them, those whose value is a program’s default, not the person’s own. differences: type: array items: type: object properties: path: type: string description: The choice’s path. asked: nullable: true description: What the person chose. programIds: type: array items: type: string description: >- The programs that do not sell it as asked and share these options. options: type: array items: nullable: true description: >- The steps they offer nearest to `asked`, lowest first. For a choice they refused (`refused`), every other step they offer. suggested: nullable: true description: >- What they price with no pick: null to price none of it. Absent when there is no suggestion: the person picks. error: type: string description: >- Why they cannot take it: the programs’ refusal of the choice, or why a pick sent in `overrides` was ignored. code: type: string description: >- With `error`: the refusal’s code, or `NOT_SOLD` for a pick of a step the program does not sell. refused: nullable: true description: >- For a choice the programs refused: the value they were rated on. required: - path - programIds - options additionalProperties: false description: >- The choices some programs cannot price as asked, with no pick for them yet, and the choices a program refused. Ask the person once which of `options` to price for those programs, and send the answer as `overrides`. A program with only one option prices it without asking; its `programs[].choices` says so. A pick of a step its program does not sell is ignored, so its difference comes back with `error` and `code: NOT_SOLD`. While any difference is open the task stays `confirm_choices`, whether or not the choice is confirmed, and each program it lists is in a `needs` state with a `choice` at its path, never `priced`. required: - kind - unconfirmed - defaulted - differences additionalProperties: false - type: object properties: kind: type: string enum: - review_results programs: type: array items: type: object properties: id: type: string description: '`programId@version`.' programId: type: string state: $ref: '#/components/schemas/V2RatingProgramPlanState' status: type: string enum: - priced - declined - invalid - open - failed description: >- Read from `state`: `invalid` for a `needs` with an `error`, `open` for any other `needs`, and `failed` also when the program is not settled and nothing asks for what it needs. provisional: type: boolean description: >- Not the end yet: a price that can still change with the next item of a list (its `state.pending` is not empty), or a decline whose reason names a list the person is still filling. waitingOn: type: array items: type: string description: The paths of what a `needs` state lists. deferred: type: array items: type: string description: Those among them the person put off. required: - id - programId - state - status - provisional - waitingOn - deferred additionalProperties: false required: - kind - programs additionalProperties: false description: >- 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: type: array items: type: object properties: path: type: string programs: type: array items: type: string description: The programs whose gaps hold it. deferred: type: boolean description: The person put it off. required: - path - programs - deferred description: >- 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: allOf: - $ref: '#/components/schemas/V2RatingProgramPlanCard' - nullable: true description: >- 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: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' description: Every open card, in asking order. answered: type: array items: type: object properties: path: type: string description: The answer’s path in `answers`. text: type: string description: >- The question, worded from the answers as they are now, as its card’s `text`. short: type: string description: >- Its short noun label, as a card’s `short`. Absent when it has none. name: type: string description: >- The current name of the list item it is about, such as “the 2020 Toyota RAV4”: `names` at its item. Absent outside a list. shown: type: string description: >- The answer in the contract’s words: an answer picked from a list by its label (“State Farm”), several by theirs, “Yes” or “No”, “None”, a date as “September 1, 2021” (“September 2021” where the question asks only the month), and an answer that was typed in as typed. Show this for an answer saved without its card. format: type: string description: >- The answer’s format, as a card’s `format`: word a number or a date your own way by it, and keep a `vin` from being shown back. precision: type: string description: >- For a date: `month` when only the month was asked, as a card’s `precision`. followUp: type: object properties: path: type: string description: The path of the question asked in this yes/no’s place. format: type: string description: That question’s `format`, such as `vin`. required: - path additionalProperties: false description: >- For a yes/no that another question is asked in the place of (a card with `noneAnswer`): that question. To change this answer, ask that question again. evidence: type: array items: type: object properties: kind: type: string label: type: string required: - kind - label description: >- The documents the answer can be read from, as a card’s `evidence`. required: - path - text additionalProperties: false description: >- 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. lists: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' description: >- 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 `_complete: true` when the person moves on. assumed: type: array items: type: object properties: path: type: string description: Where the answer would go. value: nullable: true description: The value assumed, typed as the answer is. label: type: string description: The value in the person’s words. from: type: string description: >- The answer it was read from, or the `context` key it was given under. source: type: string description: What read it (`x-filled-by.source`), `usual`, or `context`. card: allOf: - $ref: '#/components/schemas/V2RatingProgramPlanCard' - description: >- The question the value stands in for, as the plan would ask it: what to ask when the person changes what was assumed. Its answer is saved at `path` like any other. Absent when no program of the basket declares the path. required: - path - label - from - source description: >- 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: type: object additionalProperties: type: array items: type: string description: >- 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. sections: type: array items: type: string description: >- 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. labels: type: object additionalProperties: type: string description: >- 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. ready: type: array items: type: string description: The programs that are settled, as `programId@version`. changes: type: array items: type: object properties: program: type: string description: '`programId@version`.' from: type: string enum: - priced - declined - invalid - open - failed description: >- `failed`: the program could not be read or rated. The other programs plan on. to: type: string enum: - priced - declined - invalid - open - failed description: >- `failed`: the program could not be read or rated. The other programs plan on. because: type: string nullable: true description: 'For a decline: the path of the refused answer.' reason: type: string nullable: true description: 'For a decline: its message.' code: type: string nullable: true description: 'For a decline: its code.' fromState: type: string enum: - priced - needs - declined - failed description: The state’s kind sent in `previous`, when one was. toState: type: string enum: - priced - needs - declined - failed description: >- The kind of the program’s state now. Say a program has a price for `priced` here: a status of `priced` alone is a result on choices not yet confirmed. required: - program - from - to - because - reason description: >- 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: type: array items: type: object properties: path: type: string section: type: string text: type: string help: type: string kind: type: string steps: type: array items: type: object properties: value: nullable: true label: type: string programs: type: array items: type: string description: The titles of the programs that offer it. programIds: type: array items: type: string description: The programs that offer it. common: type: boolean description: >- Every insurer that sells this choice and can still quote offers this step: show these first. Insurers are counted by title, so two programs of one insurer are one, and a program that declined or could not be rated is left out. required: - label - programs - programIds - common programIds: type: array items: type: string description: >- The programs that declare this choice, in the basket’s order: who sells it, also when it lists no `steps` (a cover whose parts are each a choice of their own). required: type: boolean description: >- Some program cannot price until this choice has a value: it has a gap here. Confirmed with none, the choice is asked again with `CHOICE_REQUIRED`, so ask for a value before confirming. gates: type: array items: type: object properties: path: type: string description: The path of the choice that opens this one. value: nullable: true description: >- The value of that choice that opens this one, when the contract says the one: `true` for a yes/no, or the amount or answer the condition tests it against. Absent when it says several (`values`) or none: with neither, show this choice once that one is bought (its value is not none or no). values: type: array items: nullable: true description: >- Every value of that choice that opens this one, when the contract says more than one: show this choice while that one has one of them. Absent otherwise. required: - path additionalProperties: false description: >- The choices that open this one, each listed in `choices`: it only makes sense once they are bought, such as an upgrade of a cover or a part of one. Hide it until then. Absent for a choice that stands alone. nullable: type: boolean description: 'Some program takes `null`: “I don’t want this”.' current: nullable: true description: The value in `choices` or `answers`, if any. shape: type: string description: >- The coverage shape its contract gives it (`x-shape`): `limit`, `limit_pair`, `deductible`, `per_day`, `included`, `tier` or `term` (in months). code: type: string description: >- The shared code of what it sells (`x-code`, from the shared package’s list), such as `collision` or `bodily_injury`: what a host explains it by. Absent for a choice only one program sells. parts: type: array items: type: string description: >- For a pair of amounts, its two fields in order, such as `["limit_per_person", "limit_per_accident"]`: which part of a step’s value is which. group: type: string enum: - policy - liability - car - extras description: >- The part of the coverage screen it belongs to: `policy` (its term), `liability`, `car` (a car’s deductibles and limits) or `extras`. label: type: string description: >- A short noun for it, such as “Bodily injury”, “Collision” or “Policy length”. required: - path - text - kind - steps - programIds - required - nullable - group - label description: >- What the person buys across the basket, asked once rather than as cards. names: type: object additionalProperties: type: string description: >- Each list item’s name by its path, such as `Policy.vehicles[0]`: “the 2020 Toyota RAV4”. issues: type: array items: type: object properties: path: type: string description: The answer or choice the issue is about. code: type: string description: What is wrong with it, as a stable code. expected: nullable: true description: What the basket expects there, such as a format or a type. candidates: type: array items: nullable: true description: >- Values that may be meant, best first, to offer the person. For `NOT_SOLD`, the pick. For `CHOICE_NOT_SOLD`, what was chosen. programId: type: string description: 'For `NOT_SOLD`: the program the pick in `overrides` is for.' required: - path - code description: >- 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: type: array items: type: object properties: id: type: string description: The record a screen is about, or `checklist` or `assign`. kind: type: string enum: - item - list - checklist - confirm - assign - document - rows - extra description: >- `item`: one record’s questions of one section, ending with its list’s “any more?” on the last item; `list`: add items or say there are no more, with an inline list’s item fields; `checklist`: the declared rows of one checklist, where “None of these” answers them all; `confirm`: a checklist whose every row has a usual answer (`default`), accepted with one action; `assign`: a field naming another list’s item, on every item; `document`: the documents to read, together; `rows`: one question on every item of a list, a row per item. `extra`: the questions only some programs ask, across the records, on a screen of those programs after what every program asks; `name` lists their titles, so a host can say what answering them adds. name: type: string description: The item’s name, for an item screen. section: type: string description: >- The section every question of the screen is in: an `item` screen holds one section’s questions of its record, so head it with this. Absent for a screen across sections, such as a checklist. cards: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' description: >- Its questions, in asking order. The order does not depend on which programs ask them or on what was answered last: answering one never moves another, so keep them as they come. required: - id - kind - cards description: >- The questions packed into what a host shows at once; `next` is the first’s first. progress: type: object properties: left: type: integer description: Open questions across the basket. programs: type: array items: type: object properties: id: type: string left: type: integer required: - id - left description: Each open program’s own open questions, put-off ones aside. counted: type: boolean description: >- Whether the counts may be shown: not while the cars or drivers list is open, since every count depends on them. required: - left - programs - counted description: How much is left. programs: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true bundleId: type: string programFingerprint: type: string status: type: string enum: - priced - declined - invalid - open - failed description: >- The rater’s word for its evaluation, or `failed` when the program could not be read or rated. To decide what the person does, switch on `state.kind`: a program the rater calls `open` or `invalid` is `failed` there when nothing asks for what it needs. result: type: object additionalProperties: nullable: true description: The outputs, when priced. refusal: type: object properties: violations: type: array items: nullable: true truncated: type: boolean additionalProperties: false description: The coded decline, or the answers refused. missing: type: array items: type: object properties: path: type: string description: >- Where the answer goes in `inputs`, such as `Policy.vehicles[0].use`. reasons: type: array items: type: string choices: type: array items: nullable: true description: >- The answers the version lists, such as the rows that fit the earlier answers. With `more`, an answer outside them may also be accepted. more: type: boolean description: >- The answer may be none of `choices`: a value outside them is taken typed in. list: type: string description: A long list to search, with the list search operation. required: - path additionalProperties: false description: The answers still needed, when open. inputs: type: object additionalProperties: nullable: true evaluateMs: type: number state: $ref: '#/components/schemas/V2RatingProgramPlanState' error: type: object properties: code: type: string nullable: true description: >- A stable code to word it by: the program’s own (`LIST-MAX`, `CORE-1`), or `CHOICE_REQUIRED` (the program needs a value for a choice that was confirmed without one), `NOTHING_TO_ASK` (it is not settled and nothing asks for what it needs), or why the program could not be read or rated: `rater_unavailable` (its engine could not load or its rater did not answer), `rater_overloaded`, `rate_timeout`, `internal_evaluation_fault`, `conflict` (its engine is not the one its version names) or `no_input_contract`. Null when the program gave none. message: type: string description: Why, in the program’s or the planner’s words. required: - code - message additionalProperties: false description: >- For `failed`: why this program could not be read (its engine or its input contract) or rated. The others are still rated and planned. Its `bundleId` is its version’s, its `programFingerprint` may be empty, and it has no `choices`. waitingOn: type: integer choices: type: array items: type: object properties: path: type: string asked: nullable: true description: The value in `choices`. priced: nullable: true description: >- The value this program is rated on. For `not_offered`, the program’s own default, which it rates; null when it has none. status: type: string enum: - exact - nearest - chosen - not_offered description: >- `exact` as asked, `nearest` at the program’s nearest step, `chosen` at the person’s pick (`overrides`), or `not_offered`. nearest: nullable: true description: >- For `not_offered`: the closest step the program offers, when there is one. options: type: array items: nullable: true description: >- When the program does not price the choice as asked: the steps it offers nearest to it, lowest first. For an amount, the nearest step below and the nearest above (one past the last step); for a choice that must match, such as a term, every step it offers. suggested: nullable: true description: 'With `options`: what the program prices with no pick.' required: - path - status additionalProperties: false description: Each of `choices` as this program prices it. effectiveDate: type: string nullable: true format: date description: >- The date this program prices for, the policy’s start, as `YYYY-MM-DD`; null until answered. estimate: type: object properties: amount: type: number description: >- The price with every question not yet answered at the program’s usual or typical answer. low: type: number description: >- The low end of the range: `amount` when no open question could lower it. high: type: number description: The high end of the range. unranged: type: boolean description: >- True when the range could not be worked out: `low` and `high` are then `amount` and say nothing. termMonths: type: number description: >- With the request’s `termAt`: the policy term the amounts are for, in months. required: - amount - low - high additionalProperties: false description: >- With the request’s `priceAt`, once the program misses no answer: its estimate and the range around it. The range narrows as questions are answered; with none left open, `low` and `high` are `amount`, the price. required: - programId - version - bundleId - programFingerprint - status - state - waitingOn - choices - effectiveDate additionalProperties: false required: - asOf - answers - implied - task - open - next - questions - answered - sections - ready - changes - choices - names - issues - screens - progress - programs additionalProperties: false V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. dataset: type: string enum: - naic - osha description: Dataset needed for dataset_not_enabled. businessCode: type: string description: The rater’s own refusal code, for business_rejection. violations: type: array items: type: object properties: code: type: string description: Authored or built-in constraint code message: type: string description: Authored message for the failed constraint path: type: string description: Input path of the offending value; empty for the request value: nullable: true description: Offending input value, size-bounded by the runtime constraint: type: string description: The constraint the value failed, as text cite: type: string nullable: true description: >- Filing citation of the constraint, when the source cites one required: - code - message - path - value - constraint - cite additionalProperties: false maxItems: 256 description: >- Each input constraint the submission failed, for invalid_inputs and business_rejection. violationsTruncated: type: boolean description: >- True when the rater reported more violations than violations holds. executionId: type: string description: >- The recorded execution of a failed rating, for rater rating failures. accessUrl: type: string nullable: true format: uri description: Not currently returned. required: - code V2RatingProgramPlanCard: type: object properties: kind: type: string enum: - yesno - choice - search - multi - list - number - date - code - include - document path: type: string description: Where the answer goes in `answers`. Empty for a document. section: type: string screen: type: string description: >- The record the card belongs to, such as `Policy.vehicles[0]`. Show a screen’s cards together. screenName: type: string description: >- The name of the record the screen is, such as “the 2020 Toyota RAV4”. text: type: string description: The question. short: type: string description: >- A short noun label for the answer in a summary of answers, such as “Born”, “First licensed” or “Annual miles”. Absent when the contract declares none. because: type: object properties: path: type: string shown: type: string description: The answer as the person sees it. priced: type: array items: type: object properties: programId: type: string shown: type: string description: The step this program is rated on, in words. required: - programId - shown additionalProperties: false description: >- When the answer is something the person buys: each program that asks this card and is rated on another step than the one asked for (its nearest step, or the person’s pick for it). The card is that program’s because of its own step, so say it: “because Carrier prices a $500 deductible”. Absent when every asker prices it as asked. required: - path - shown description: 'For a follow-up: the answer that made it relevant.' related: type: object properties: path: type: string shown: type: string description: The answer as the person sees it. priced: type: array items: type: object properties: programId: type: string shown: type: string description: The step this program is rated on, in words. required: - programId - shown additionalProperties: false description: >- When the answer is something the person buys: each program that asks this card and is rated on another step than the one asked for (its nearest step, or the person’s pick for it). The card is that program’s because of its own step, so say it: “because Carrier prices a $500 deductible”. Absent when every asker prices it as asked. required: - path - shown description: 'For a refinement: the answer it refines.' waitsOn: type: array items: type: string description: >- For a question whose answers depend on another answer that is not given yet (a car’s model on its make, its make on its year): the path of every such question, nearest first, each a card of the same plan. Show the card with them and take its answer only once they are answered, since their answers narrow its `choices`. Absent when it waits on nothing. why: type: object properties: askedBy: anyOf: - type: string enum: - all - type: array items: type: string description: '`all` when every open program asks it, else their titles.' blocks: type: array items: type: string description: The programs whose result waits on the answer. reasons: type: object additionalProperties: type: string description: Each asker’s reason, by title. stillSettled: type: integer nullable: true description: >- What skipping costs: how many other insurers price, or can still price, without the answer (two programs of one insurer count once). The host words it. Some of them may still be open: only `stillPriced` of them have a price. stillPriced: type: integer description: >- With `stillSettled`: how many of those insurers already have a result without the answer. Say “N other prices” of these only; the rest can still price, and may yet decline or ask more. required: - askedBy - blocks - reasons - stillSettled help: type: string evidence: type: array items: type: object properties: kind: type: string label: type: string required: - kind - label description: The documents the answer can be read from, for the host to word. choices: type: array items: type: object properties: value: nullable: true label: type: string help: type: string description: What the answer means, when the contract says. aliases: type: array items: type: string description: >- For `search`: other names for the answer. A host that searches the card’s choices matches them as the list search operation does. catchAll: type: boolean description: >- The answer stands for every answer the list does not name, such as “Something else” or “Not sure”. Such answers come last in `choices`: keep that order. A host that searches a `search` card’s choices offers these, in order, when what the person typed matches none. required: - label list: type: string description: >- The list to search, for `search`; for `more`, the path of the list it asks about, such as `Policy.vehicles`. format: type: string precision: type: string enum: - month description: 'For a date: the person picks a month; save its first day.' picker: type: string description: >- For `search`: how to show its answers, such as `logo` beside each make. addLabel: type: string description: >- For `list` and `more`: the words of the button that adds an item, “Add a car”. itemName: type: string description: >- For `list` and `more`: the name to ask for each item and keep (“First name”), never sent to a program; send them back as `displayNames`. pattern: type: string min: nullable: true description: >- The smallest answer, or the fewest items. For a date, also the bound other answers give, such as today for a policy’s start. max: nullable: true description: >- The largest answer, or the most items. For a date, also the bound other answers give, such as 15 years before the policy starts for a birth date. whole: type: boolean description: 'For `number`: whole numbers only.' decimals: type: integer description: >- For `number`: the decimal places the answer takes, when the contract says how fine it is, such as 2 for an amount in cents and 0 for whole numbers. Absent when it says nothing: keep the answer as typed, and never round it. key: type: string nullable: type: boolean description: '`null` is an answer too: it says none, and nothing asks there again.' you: type: object properties: field: type: string value: nullable: true required: - field description: >- For a list: which item is the person answering. The person adds themselves first, so write this field on the first item. more: type: boolean description: >- The answer may be none of `choices`: they are the rows that fit the earlier answers, and a value outside them is taken typed in. Absent when any program of the basket takes only its listed answers there, whatever the others take: `choices` are then the only answers. revisit: type: boolean description: The person skipped this card before. error: type: string description: Why the answer given was refused. errorCode: type: string description: 'With `error`: the refusal’s code, when it has one.' refusedBy: type: array items: type: string description: >- With `error`: the programs that refused the answer. When several did, `error` is the first one’s; each program’s own is in its `state`. document: type: string answers: type: integer description: 'For a document: how many open questions it answers.' suggested: type: object properties: value: nullable: true from: type: string name: type: string nullable: true source: type: string description: >- Set when the answer is worked out from another, such as `vin_decode` for one from the car’s VIN at `from`; absent for the item before’s answer. label: type: string description: >- The value in the person’s words, as the card’s choice for it reads (“Front-wheel drive”): the answer it saves, never the source’s own words. required: - from description: >- An answer offered as a one-tap answer: the same question’s answer on the item before, or one worked out from another answer, such as the car’s VIN. The person takes it or answers over it. checklist: type: string description: The checklist this card is a row of, as the contract declares it. default: nullable: true description: >- The usual answer (`x-common`, or a `context` value the contract names), typed as the answer is: what an estimate assumes until the person answers, and what a `confirm` screen shows. Never saved for the person unless they accept it. askFirst: type: boolean description: No estimate is shown until this is answered (`x-ask-first`). blocksEstimate: type: boolean description: >- No program of the basket can have an estimate without this answer: every open program asks it, and for each it is `askFirst` or has no usual answer and is not a list that counts as none until answered. Such questions are asked before those that do not. Which programs wait on a question only some of them ask is `estimateWaitsOn`. shownWhen: type: array items: type: object properties: path: type: string description: A question on the same screen. values: type: array items: nullable: true description: The answers there that open this one. required: - path - values description: >- A follow-up shown on the screen of the questions it follows: show it once each of them has one of `values`, and do not ask it otherwise. It is listed right after them. code: type: object properties: fold: type: array items: type: string description: >- The formatting an entry may be folded by: `upper case`, `spaces`, `dashes`. length: type: integer description: The full form’s length. alphabet: type: string description: Every character the full form may hold. check: type: string description: The check the full form must pass, as the contract declares it. reduce: type: string description: >- How a valid full form is cut to the kept form, which matches `pattern`. required: - fold - reduce description: >- For a code kept in a shorter form than the one typed: how to check an entry as it is typed, before saving. The entry, folded only as `fold` says, is accepted if it matches `pattern` (the kept form) or is exactly `length` characters of `alphabet` whose `check` holds; anything else is refused, never cut or padded. The API checks again on every save. statement: type: string description: >- A checklist row’s words: a statement that is true of the item or not. noneAnswer: type: object properties: label: type: string gate: type: string required: - label - gate description: >- The answer that says this follow-up’s yes/no is no, such as “I don’t have it”: the yes/no at `gate` is asked as this card, with this answer beside the question. When it is taken, set `gate` to false, or save `null` at the card’s `path`: `null` there says none, and implies `gate` is false. Any other answer implies `gate` is true. Either way `implied` returns the yes/no, so you never need to write `gate` yourself. An answer you do send at `gate` is kept, but a `true` beside `null` at this card’s `path`: that `null` says none, so `implied` returns `gate` as `false`; store it. Put the card off by its own `path`. A card with it is never `nullable`: this answer is the one way to say none. A follow-up asked for itself, its yes/no already yes, carries it too when no program requires the answer. required: - kind - path - text V2RatingProgramPlanState: oneOf: - type: object properties: kind: type: string enum: - priced pending: type: array items: type: string description: >- The questions about the household’s lists that are still asked, such as `Policy.vehicles_complete` (“any more cars?”): the price can change with the next item. Each is a card in `questions`. Empty when the price is final. required: - kind - pending additionalProperties: false - type: object properties: kind: type: string enum: - needs items: type: array items: type: object properties: path: type: string description: >- For `answer`, the path of a card in `questions`; for `choice`, of an entry in `choices`. kind: type: string enum: - answer - choice description: >- `answer`: a question to answer. `choice`: something to choose or confirm on the coverage screen, or a `differences` entry to pick for. deferred: type: boolean description: The person put it off. error: type: object properties: code: type: string nullable: true description: >- A stable code to word it by: the program’s own (`LIST-MAX`, `CORE-1`), or `CHOICE_REQUIRED` (the program needs a value for a choice that was confirmed without one), `NOTHING_TO_ASK` (it is not settled and nothing asks for what it needs), or why the program could not be read or rated: `rater_unavailable` (its engine could not load or its rater did not answer), `rater_overloaded`, `rate_timeout`, `internal_evaluation_fault`, `conflict` (its engine is not the one its version names) or `no_input_contract`. Null when the program gave none. message: type: string description: Why, in the program’s or the planner’s words. required: - code - message additionalProperties: false description: >- Why the program refused what was given there, (`CHOICE_REQUIRED`) that it needs a value for a choice that was confirmed without one: the choice is then in `unconfirmed` again, or (`NOT_SOLD`) that the pick sent for it in `overrides` is of a step it does not sell: its `differences` entry is asked again. Absent the first time something is asked. Show it at the path; the same thing is never asked again without one. required: - path - kind - deferred additionalProperties: false minItems: 1 description: >- What the program needs from the person, in asking order. Never empty. required: - kind - items additionalProperties: false - type: object properties: kind: type: string enum: - declined reason: type: object properties: code: type: string nullable: true description: >- A stable code to word it by: the program’s own (`LIST-MAX`, `CORE-1`), or `CHOICE_REQUIRED` (the program needs a value for a choice that was confirmed without one), `NOTHING_TO_ASK` (it is not settled and nothing asks for what it needs), or why the program could not be read or rated: `rater_unavailable` (its engine could not load or its rater did not answer), `rater_overloaded`, `rate_timeout`, `internal_evaluation_fault`, `conflict` (its engine is not the one its version names) or `no_input_contract`. Null when the program gave none. message: type: string description: Why, in the program’s or the planner’s words. required: - code - message additionalProperties: false description: The decline’s first reason. change: type: array items: type: string description: >- The answers and choices the decline names, in order: changing one may change the decline. A rule of the policy or of a list item is named by the answers it read, the program’s own question first, such as `Policy.member` before `Policy.current_insurer`; one that read none of the person’s answers is named as the record, such as `Policy` or `Policy.vehicles[0]`, as is a list item’s key. May be empty. required: - kind - reason - change additionalProperties: false - type: object properties: kind: type: string enum: - failed reason: type: object properties: code: type: string nullable: true description: >- A stable code to word it by: the program’s own (`LIST-MAX`, `CORE-1`), or `CHOICE_REQUIRED` (the program needs a value for a choice that was confirmed without one), `NOTHING_TO_ASK` (it is not settled and nothing asks for what it needs), or why the program could not be read or rated: `rater_unavailable` (its engine could not load or its rater did not answer), `rater_overloaded`, `rate_timeout`, `internal_evaluation_fault`, `conflict` (its engine is not the one its version names) or `no_input_contract`. Null when the program gave none. message: type: string description: Why, in the program’s or the planner’s words. required: - code - message additionalProperties: false description: Why. The way out is to try again later. required: - kind - reason additionalProperties: false description: >- The one state the program is in: switch on its `kind`, not on `status`. Every state but `priced` carries its own way out: `needs` says what to answer or choose, `declined` what to change, `failed` to try again. `priced` is final: every choice the program prices is in `confirmed`, and no entry of `differences` asks the person to pick for it. A program rated with a result on choices that are not confirmed is `needs`, with a `choice` for each of them, while its `status` is `priced` and its `result` is set: confirming the choices may ask more questions, so do not show that result as its price. The same holds while a `differences` entry lists the program: it is rated at its nearest step, `needs` a `choice` at that path, and the pick may ask more questions. Following the plan, a `priced` program stays `priced` unless the person changes an answer or a choice, or adds a list item. A pick in `overrides` that the program does not sell counts as none: the program still `needs` the choice, now with a `NOT_SOLD` error, and `differences` asks again. V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.