Rate a submission with a program

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. You need an Effective API key with raters:run, and your organization needs access to run the program. Get a rating program explains access and subscriptions.

1. Find a program

List rating programs and filter by state:

curl --request GET \
  --url "https://api.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 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.

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:

curl --request GET \
  --url "https://api.effectiveai.app/api/v2/insurance/rating-programs/$PROGRAM/versions/$VERSION/contract" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"

Get the input and output schemas 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 with the policy in inputs. This example uses Effective’s synthetic effective.example-ca-ppa program:

curl --request POST \
  --url "https://api.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:

{
  "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:

{
  "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. It downloads each program and rates locally on the same native engine:

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.

Market Directory

Carriers and products

Rating programs

Filings

Carrier financials

Regulations

Risk information

Rate a submission with a program

1. Find a program

2. Read the input schema

3. Rate

Errors

Rate a book in Python

​1. Find a program

​2. Read the input schema

​3. Rate

​Errors

​Rate a book in Python

1. Find a program

2. Read the input schema

3. Rate

Errors

Rate a book in Python