> ## Documentation Index > Fetch the complete documentation index at: https://docs.canary.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). 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. Coverage is chosen, not asked: `choices` in the response lists each limit, deductible or term the basket prices, with every program's steps. 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. 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.canary.effectiveai.app/api/v2 description: Canary 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). 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. Coverage is chosen, not asked: `choices` in the response lists each limit, deductible or term the basket prices, with every program's steps. 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. 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 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 - version additionalProperties: false minItems: 1 maxItems: 10 description: >- Pinned program versions. 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. 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 status: type: string enum: - priced - declined - invalid - open required: - programId - version - status additionalProperties: false maxItems: 10 default: [] description: >- Each program’s status from the previous call. `changes` lists the programs whose status 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. 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. When a program does not sell a choice as asked, `task.differences` says so and `overrides` takes the person’s pick. 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). 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: >- 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. task: oneOf: - type: object properties: kind: type: string enum: - answer_screen screen: type: object properties: id: type: string kind: type: string name: type: string 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. 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. required: - path - programIds - options additionalProperties: false description: >- The choices some programs cannot price as asked, with no pick for them yet. 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. While any difference is open the task stays `confirm_choices`. 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`.' status: type: string enum: - priced - declined - invalid - open provisional: type: boolean description: >- The result can still change with the next car or driver: the household’s lists are open. waitingOn: type: array items: type: string description: The paths an open program waits on. deferred: type: array items: type: string description: Those among them the person put off. required: - id - status - provisional - waitingOn - deferred additionalProperties: false required: - kind - programs additionalProperties: false description: >- The one thing the person does next: `answer_screen` while an open question is not put off; else `confirm_choices` while a choice is not confirmed; else `review_results`, each program where it stands. 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. questions: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' description: Every open card, in asking order. 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 to: type: string enum: - priced - declined - invalid - open 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.' required: - program - from - to - because - reason description: Each program whose status differs from `previous`. 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 program of the basket that sells this choice offers this step: show these first. required: - label - programs - programIds - common 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. required: - path - text - kind - steps - nullable 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. required: - path - code description: >- Answers in `answers` or `choices` that the basket’s contracts cannot read as sent. Correct each and plan again. 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 - assign - document - rows description: >- `item`: one record’s questions, 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; `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. name: type: string description: The item’s name, for an item screen. cards: type: array items: $ref: '#/components/schemas/V2RatingProgramPlanCard' 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: allOf: - $ref: '#/components/schemas/V2RatingProgramOpenRateResult' - type: object properties: 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. required: - waitingOn - choices additionalProperties: false required: - asOf - answers - task - open - next - questions - 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. because: type: object properties: path: type: string shown: type: string description: The answer as the person sees it. 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. required: - path - shown description: 'For a refinement: the answer it refines.' 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 programs still settle without the answer. The host words it. 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 required: - label list: type: string description: The list to search, for `search`. format: type: string pattern: type: string min: nullable: true max: nullable: true whole: type: boolean key: type: string nullable: type: boolean 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. revisit: type: boolean description: The person skipped this card before. error: type: string description: Why the answer given was refused. 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. 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. 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”: offer it beside the question; when it is taken set `gate` to false, and with any other answer set `gate` to true. required: - kind - path - text V2RatingProgramOpenRateResult: 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 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 required: - programId - version - bundleId - programFingerprint - status additionalProperties: false 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.