> ## 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.

# Rate a submission with a program

> Find a rating program, read its input schema, and rate one policy on Effective's native RSL engine with one HTTP request.

Hosted rating runs one program version on Effective's servers. You send one policy as JSON. The
native RSL engine checks the policy against the program's input rules, then rates it. You get the
premium and its parts, or a list of each rule the policy failed.

```mermaid theme={null}
sequenceDiagram
  participant You
  participant API as Effective API
  participant Engine as Native RSL engine
  You->>API: GET /insurance/rating-programs?state=CA
  API-->>You: programs[] (id, access)
  You->>API: GET .../versions/{version}/contract
  API-->>You: inputSchema, outputSchema
  You->>API: POST .../versions/{version}/rate {inputs}
  API->>Engine: admit inputs, then rate
  Engine-->>API: outputs or violations
  API-->>You: 200 result, or 422 violations
```

You need an [Effective API key](/getting-started/authentication) with `raters:run`, and your
organization needs access to run the program. [Get a rating program](/guides/get-rating-program)
explains access and subscriptions.

## 1. Find a program

[List rating programs](/api-reference/rating-programs/list-rating-programs) and filter by state:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/rating-programs?state=CA" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

Each item in `programs` has an `id`, its carrier, product and states, and `access.canRun`. Use a
program whose `access.canRun` is `true`. Then
[list its versions](/api-reference/rating-programs/list-program-versions) and choose a `version`.
To find the program that rates a product in a state on a date, use
[List which rating program versions rate a product in a state](/api-reference/products/list-which-rating-program-versions-rate-a-product-in-a-state).

## 2. Read the input schema

Each version has its own input. The input is the program's root record, such as `Policy`, with its
related records (drivers, vehicles) nested inside it. Programs from different carriers ask for
different fields, so read the schema of the version you rate:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/rating-programs/$PROGRAM/versions/$VERSION/contract" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

[Get the input and output schemas](/api-reference/rating-programs/get-the-input-and-output-schemas-of-a-program-version)
returns `inputSchema` and `outputSchema` as JSON Schema. Each field holds its type, its allowed
values, and its range. You or your tooling can build and check a request from `inputSchema` alone.

## 3. Rate

[Rate a submission](/api-reference/rating-programs/rate-a-submission) with the policy in `inputs`.
This example uses Effective's synthetic `effective.example-ca-ppa` program:

```bash theme={null}
curl --request POST \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/rating-programs/effective.example-ca-ppa/versions/1/rate" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "inputs": {
      "Policy": {
        "years_with_us": 3,
        "multi_policy": true,
        "drivers": [{ "number": 1, "years_licensed": 12, "incidents": [] }],
        "vehicles": [{
          "number": 1, "vehicle_age": 4, "garaging_zip": "94110", "make_model": "TOYOTA/CAMRY",
          "bodily_injury_limit": "100/300", "property_damage_limit": "50",
          "combined_single_limit": false, "uninsured_motorist_property_damage": false,
          "collision_deductible_waiver": false, "custom_equipment_limit": 0,
          "loan_gap": false, "roadside": false
        }]
      }
    }
  }'
```

A `200` response holds the outputs in `result`, in the shape of `outputSchema`, and the exact engine
that rated them:

```json theme={null}
{
  "programId": "effective.example-ca-ppa",
  "version": 1,
  "bundleId": "…64 hex characters…",
  "result": {
    "Policy": {
      "premium": 898,
      "vehicles": [
        {
          "coverage_premium": {
            "bodily_injury": 547,
            "property_damage": 351,
            "collision": 0,
            "…": 0
          },
          "endorsement_premium": { "roadside": 0, "…": 0 }
        }
      ],
      "drivers": [{ "incidents": [] }]
    }
  },
  "timings": { "workerMs": 6.1, "evaluateMs": 4.4 }
}
```

Numbers in `result` are JSON numbers with 64-bit float precision, about 15 significant digits. Keep `programId`, `version` and `bundleId` with each result:
together they identify the engine that rated it. The request changes nothing, so you can repeat it.

## Errors

Every error has a stable `code` and an `error` message. Rating errors also explain the cause:

```json theme={null}
{
  "code": "business_rejection",
  "error": "The program writes one to six rated drivers.",
  "businessCode": "DRIVER-COUNT",
  "violations": [
    {
      "code": "INPUT-ENUM",
      "message": "bodily_injury_limit must be one of: 30/60, 50/100, 100/300, 250/500, 500/500",
      "path": "Policy.vehicles[0].bodily_injury_limit",
      "value": "1/2",
      "constraint": "bodily_injury_limit: Enum(BiLimit)",
      "cite": null
    },
    {
      "code": "DRIVER-COUNT",
      "message": "The program writes one to six rated drivers.",
      "path": "Policy.drivers",
      "value": 0,
      "constraint": "drivers: where len(self) in [1, 6]",
      "cite": "manual:anchor \"eligibility\""
    }
  ],
  "violationsTruncated": false
}
```

| Status | `code` | Cause | What to do |
| - | - | - | - |
| 400 | `invalid_request` | The URL or body is malformed, for example `inputs` is missing. `details` lists each field. | Fix the request. |
| 401 | `unauthenticated` | The API key is missing or invalid. | Send `Authorization: Bearer <key>`. |
| 403 | `forbidden` | Your organization cannot run this program, or your key lacks `raters:run`. | Check `access.canRun` on the program. |
| 404 | `not_found` | The program or version does not exist. | List programs and versions again. |
| 409 | `conflict` | The stored engine differs from the published version. | Retry later and report the `requestId`. |
| 413 | `request_too_large` | The body is larger than 1 MiB. | Send one policy per request. |
| 415 | `unsupported_media_type` | The body is not JSON. | Send `Content-Type: application/json`. |
| 422 | `invalid_inputs` | The policy breaks the input schema: a missing field, a wrong type, a value out of range. | Fix each item in `violations`. |
| 422 | `business_rejection` | The policy is valid input, but the filing does not let the program write it. `businessCode` names the rule. | Do not retry the same policy; `violations[].cite` gives the source in the filing. |
| 422 | `evaluation_failed` | The program could not compute a premium for this policy. | Report the request to Effective. |
| 429 | `rater_overloaded` | The engine is busy. | Retry after the `Retry-After` header. |
| 503 | `rate_timeout`, `rater_unavailable` | The engine did not answer in time, or could not start. | Retry after `Retry-After`. |
| 500 | `internal_error` | An unexpected server failure. | Retry once, then report the `requestId`. |

In `violations`, `path` locates the field in your input, `value` repeats what you sent, and
`constraint` is the rule it failed. `violationsTruncated` is `true` when there were more violations
than the response lists.

## Rate a book in Python

To rate many policies, or the same book across several programs, use
[Relativities](/relativities/setup). It downloads each program and rates locally on the same
native engine:

```python theme={null}
from relativities import Program

program = Program.load("effective://example-ca-ppa")
results = program.rate(program.example_book)
```

`Program.rate` maps one shared book onto each carrier's own input, so one book rates against every
program. See [Rate a book with a program](/relativities/how-to/rate-a-book-with-a-program).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.