> ## 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. # Match a said or read answer to a planning question > Find what an answer said in words or read from a document means for one planning question, across the same market rater versions as [Plan the next question](/api-reference/market-raters/plan-the-next-question-for-market-rater-versions). Send `programs` as you sent them there: a program without a `version` is read at the version this server rates with. The result is `exact` with the value to store at `path`, `candidates` (a date written two ways), `none`, or `refused` with why. Saving never chooses among answers: for a question with listed answers only a listed value or label as written matches (case, spacing and punctuation folded); anything else is `refused` with `search`, and [Search the answers of a planning question](#) finds what was meant. What is read is how a value is written: dates in forms that parse one way, amounts such as `100k` and `$100,000`, limits such as `100/300`, a ZIP+4 as its ZIP, and a code kept shorter than it is typed as its kept form or its whole full form whose check holds (`x-reduce`, `x-check`), else `refused` with the rule it broke. Send `answers` when the question's answers depend on earlier ones, as a car's model does on its make. A version that cannot be read or rated is not asked: `notAsked` names it with why, and the match is the other versions' alone. The request fails only when no version can be asked. Needs access to rate every named version and your `raters:run` permission. Matching changes nothing, so the request is safe to repeat. ## OpenAPI ````yaml /openapi.json post /insurance/rating-programs/match 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/match: post: tags: - Market raters summary: Match a said or read answer to a planning question description: >- Find what an answer said in words or read from a document means for one planning question, across the same market rater versions as [Plan the next question](/api-reference/market-raters/plan-the-next-question-for-market-rater-versions). Send `programs` as you sent them there: a program without a `version` is read at the version this server rates with. The result is `exact` with the value to store at `path`, `candidates` (a date written two ways), `none`, or `refused` with why. Saving never chooses among answers: for a question with listed answers only a listed value or label as written matches (case, spacing and punctuation folded); anything else is `refused` with `search`, and [Search the answers of a planning question](#) finds what was meant. What is read is how a value is written: dates in forms that parse one way, amounts such as `100k` and `$100,000`, limits such as `100/300`, a ZIP+4 as its ZIP, and a code kept shorter than it is typed as its kept form or its whole full form whose check holds (`x-reduce`, `x-check`), else `refused` with the rule it broke. Send `answers` when the question's answers depend on earlier ones, as a car's model does on its make. A version that cannot be read or rated is not asked: `notAsked` names it with why, and the match is the other versions' alone. The request fails only when no version can be asked. Needs access to rate every named version and your `raters:run` permission. Matching changes nothing, so the request is safe to repeat. operationId: matchRatingProgramAnswer 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. path: type: string maxLength: 500 pattern: >- ^[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*(\.[A-Za-z_][A-Za-z0-9_]*(\[\d+\])*)*$ description: The card’s path, such as `Policy.drivers[0].occupation`. value: nullable: true description: 'The answer as said or read: text, or a value.' answers: type: object additionalProperties: nullable: true description: >- Every answer so far. Send it when the card’s answers depend on earlier ones, such as a car model on its make. An answer already stored at `path` is left out when the programs are rated, so it never narrows its own choices. required: - programs - path additionalProperties: false responses: '200': description: The matched value, the candidates, or none. content: application/json: schema: $ref: '#/components/schemas/V2RatingProgramMatch' '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: V2RatingProgramMatch: anyOf: - type: object properties: exact: nullable: true description: The stored value to answer with. notAsked: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true 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 it could not be asked, as a failed program’s `state.reason`. required: - programId - version - reason additionalProperties: false description: >- The programs that could not be asked: one that could not be read is asked nothing, and one that could not rate `answers` gave none of the choices they narrow. The match is the other programs’ alone, so an answer only these programs take reads as `none`. Absent when every program was asked. additionalProperties: false - type: object properties: candidates: type: array items: type: object properties: value: nullable: true label: type: string required: - label description: The answers that may be meant, best first. notAsked: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true 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 it could not be asked, as a failed program’s `state.reason`. required: - programId - version - reason additionalProperties: false description: >- The programs that could not be asked: one that could not be read is asked nothing, and one that could not rate `answers` gave none of the choices they narrow. The match is the other programs’ alone, so an answer only these programs take reads as `none`. Absent when every program was asked. required: - candidates additionalProperties: false - type: object properties: none: type: boolean enum: - true notAsked: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true 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 it could not be asked, as a failed program’s `state.reason`. required: - programId - version - reason additionalProperties: false description: >- The programs that could not be asked: one that could not be read is asked nothing, and one that could not rate `answers` gave none of the choices they narrow. The match is the other programs’ alone, so an answer only these programs take reads as `none`. Absent when every program was asked. required: - none additionalProperties: false - type: object properties: refused: type: object properties: reason: type: string enum: - search - length - character - check - form description: >- `search`: no listed value or label as written; search the answers for it (saving never chooses). For a code kept shorter than it is typed: `length` (neither form’s length), `character` (one the code never holds), `check` (it looks mistyped), `form` (the kept form’s length, not its form). expected: type: integer description: 'For `length`: the length wanted.' got: type: integer description: 'For `length`: the length entered.' character: type: string description: 'For `character`: the character.' position: type: integer description: 'For `character`: where, from 1.' required: - reason additionalProperties: false description: The entry is refused, and why. Nothing is guessed. notAsked: type: array items: type: object properties: programId: type: string version: type: integer minimum: 0 exclusiveMinimum: true 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 it could not be asked, as a failed program’s `state.reason`. required: - programId - version - reason additionalProperties: false description: >- The programs that could not be asked: one that could not be read is asked nothing, and one that could not rate `answers` gave none of the choices they narrow. The match is the other programs’ alone, so an answer only these programs take reads as `none`. Absent when every program was asked. required: - refused 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 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.