Skip to main content
Rating over the API never writes the returned rating fields for you. Both POST /api/v1/companies/{companyId}/quotes/rate (rate a prospective quote from a request body) and POST /api/v1/companies/{companyId}/quotes/{quoteId}/rate (rate an already-saved quote by id) compute rating results and return them in the response. Rating by id records only the successfully used workflow as Quote system metadata; the saved quote’s field bag remains byte-identical. If you want the results stored on the quote, write them back yourself; see Rating results are not persisted and Persisting rating results. Hosted rating supports new-business, renewal, and endorsement quotes. External rating (“bring your own engine”) works today via the existing entity-update endpoints (see below). See the Roadmap for overall API direction.
The Rating API lets you compute premium and rating results for a quote or endorsement. Two approaches serve different use cases, and they can be used together.

​
Hosted Rating

Invoke the AI Insurance-configured rating engine for a quote. The system runs the configured rating workflow (per company) and computes the rating results. Hosted rating supports quote types newBusiness, renewal, and endorsement. It does not rate cancellation or reinstatement quotes: those transactions preserve the source policy’s rating result and derive cancellation pricing from earned amounts or restore pre-cancellation pricing. Either unsupported quote type returns a structured 400 InvalidRequest before a configured rater or vendor is called.

​
Rating Results Are Not Persisted

Neither rating endpoint persists the returned field values. This is the single most important thing to know about the Rating API. Concretely, for both endpoints:
  • No field is written to the quote. The quote row is byte-identical before and after the call — same field values, same updatedAt.
  • No rating run is recorded, and no entity is created or changed.
  • The exposure lookup rating performs (see below) is read-only.
The by-id endpoint has one narrow saved-quote effect: after a successful run, it records the requested ratingWorkflowName as Quote system metadata. Later quote workflows can therefore identify the workflow used for the retained rating. A failed run leaves the existing selection unchanged. Rating is not, however, free of effects outside the returned field bag: a rate runs your configured rating workflow for real, which may call an external rating vendor and is logged like any other API call.
Because rating does not write its returned fields, the results exist only in the response you are holding. A response you discard leaves no rating values on the quote (although a successful by-id call has recorded its workflow selection). To store rating results on a quote, write them back explicitly — see Persisting rating results.
If you have used the AI Insurance app, note that the underwriter workbench’s Generate Rating button behaves the same way: it fills the quote form the underwriter is looking at with the freshly rated values, and those values reach the database only when the quote is saved. The save is the write — there and here. The difference over the API is simply that you perform the save yourself.

​
Persisting Rating Results

Keeping the results is a separate, explicit update, made with the ordinary entity-update endpoints:
  1. Rate the quote (either endpoint), require a successful response with a data bag, and verify that it contains the pricing you expect.
  2. Copy the rating-owned fields from that returned data bag into a PATCH to /api/v1/companies/{companyId}/entities/quote/{entityId}. In particular, copy fullTermPricingInfo — including its pricingComponents and computed totals — when the rate response contains it. The bind operation reads the persisted quote, not the earlier rate response.
  3. Read the quote back with GET /entities/quote/{entityId} and verify that the persisted fields match the rate result. External API responses are marked Cache-Control: no-store, so this read is a live post-commit view.
  4. Bind only after that verification. Once a quote is bound, generic quote updates are rejected; make later changes through policy transactions. For an in-force policy, write rating changes through a policy endorse transaction instead.
The mechanics are the same ones described under External Rating below — to the write path, hosted rating results are just field data.
A rate response reflects only the run that produced it. Every rating workflow clears the containers it owns — the pricing and rating-response containers its stages write — before any rater runs, and rebuilds them from that run’s output. Two consequences worth designing around:
  • Stale values you send are not echoed back. If the body you POST to /quotes/rate still carries rating containers from an earlier run, they are cleared before rating and rewritten from the fresh rater output. The response carries this run’s money, never a copy of what you sent.
  • A rate that prices nothing comes back cleared, not unchanged. If the workflow’s raters produce no money for this quote (an incomplete quote, a workflow whose stages all no-op), the rating-owned containers come back empty rather than carrying whatever was stored before. Writing that response back wholesale therefore clears the previously stored figures. If you re-rate and persist as one step, check the response for the values you expect before writing it back.

​
Live Endpoints

The full-body rate endpoint takes { ratingWorkflowName, data }, where data is the exact create-quote field bag. It validates data with the create-quote pipeline (a body create-quote would reject fails with the identical 400), runs the named rating workflow, and returns { data } — the same bag enriched with rating outputs. It writes no quote and records no rating run. ratingWorkflowName is required: a missing/unknown name returns a 400 listing the configured names, and a company with no workflows configured returns a 422. Because embedded exposures are referenced by id over the API (you cannot inline-create an exposure), exposure id references are looked up and merged: each referenced Exposure’s stored fields are fetched and merged under the reference before rating, so the exposure is rated against its real stored data. Fields you supply inline win over the stored values (the body is a draft-edit over the stored exposure). This lookup is read-only. If a rating target the selected workflow requires — e.g. quote.exposures — is empty or missing on the quote after this merge, the endpoint returns a 400 naming the workflow and the target path. The by-id rate endpoint takes just { ratingWorkflowName } in the body and the quote id in the path. It loads the saved quote’s stored field bag and runs the identical pipeline — the same create-quote validation, the same exposure id hydration, the same rating workflow — returning { data }, the saved quote’s bag enriched with rating outputs. No field is written and no rating run is recorded, so the quote row is byte-identical before and after. On success, the named workflow is recorded separately as Quote system metadata; on a failed rate, the previous selection is preserved. Storing the returned rating fields is still your explicit second call (Persisting rating results). For a supported quote type, any saved quote rates regardless of its quoteStatus (including bound and cancelled); this status promise does not make unsupported cancellation or reinstatement quote types ratable. There are deliberately no data overrides — to rate what-if values, use the full-body /quotes/rate endpoint instead (GET the quote, tweak, and POST it there). ratingWorkflowName behaves identically (missing/unknown → 400 listing the configured names; no workflows configured → 422), an unknown / deleted / other-company / non-quote id returns a 404, and a saved quote whose stored data no longer validates against your current configuration returns the same structured 400.

​
Rating Failures Return 200 With diagnostics

On both rate endpoints, a failure during rating execution returns HTTP 200 with a diagnostics array ([{severity, code, message, location?}]) and no data. That covers rating vendor errors, quote-data faults a rater rejects (e.g. a required rating input that is present but not numeric), mis-wired rating stages (a bad outputPath or missing rater args), errored workbook output cells, and spreadsheet outputs that never settle. The absent data field is the failure signal: check for data to detect success, not the HTTP status, and do not treat the presence of diagnostics alone as failure — a successful rate can carry severity: warning diagnostics alongside its data (e.g. a rated output value that could not be written to the quote and was skipped). Each diagnostic may carry a location naming where in the rating workflow it arose (stage, rater debug name, target path, and the rated segment windows); failures classified outside any one stage stay location-free. Invalid requests keep their status codes — the 400, 404, and 422 behaviors described above are unchanged — and unexpected application faults are still 500.

​
Planned Endpoints

​
How It Works

  1. Call the appropriate rating endpoint for your use case
  2. The system invokes the rating engine configured for your company
  3. The computed rating results are returned in the response, enriched onto the quote’s field bag — the returned fields are not persisted. A successful by-id call records only its workflow selection
  4. To keep the results, write them back yourself — see Persisting rating results

​
When to Use

  • You use AI Insurance’s built-in rating engine
  • You want the system to compute premium based on your configured rating logic
  • You want to preview or recompute premium without changing the stored quote fields
  • You want the premium stored too: rate, then write the results back as a second, explicit call (Persisting rating results)

​
External Rating (Bring Your Own Engine)

External rating is available today — no new endpoint is needed. If you compute rating externally, write your rating results directly to the quote (or policy endorsement) using the existing update endpoints.

​
How It Works

  1. Compute rating results in your own system
  2. Update the quote via PATCH /api/v1/companies/{companyId}/entities/quote/{entityId} with the rating outputs populated, including fullTermPricingInfo when your engine produced it. For an in-force policy, write rating results through a policy endorse transaction instead.
  3. The system treats these as regular field data — no special handling required

​
When to Use

  • You have a proprietary rating engine
  • Rating is computed outside AI Insurance
  • You need full control over the rating calculation

​
Both Approaches Work Together

The API doesn’t require rating results to come from any specific source. Whether you use hosted rating, external rating, or a combination, the downstream workflow is the same: once rating fields are populated on a quote or endorsement, it can proceed through the workflow.

​
Permissions

  • Entities API — create and manage quotes
  • Policy API — create policies from rated quotes via the transaction model
  • Roadmap — overall API direction