Skip to main content
Stateless quote rating is live — 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 without persisting anything. 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 is stateless. The computed rating outputs are returned in the response, enriched onto the quote’s field bag — nothing is written to the quote, and no rating run is recorded. If you want to keep the results, persisting them is a separate update you make with the entity-update endpoints (see External Rating below). 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.

​
Live Endpoints

The stateless 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. It never modifies the quote: no field is written and no rating run is recorded, so the quote row is byte-identical before and after. 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.

​
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 — nothing is persisted
  4. To keep the results, write them back yourself with the entity-update endpoints (see External Rating below)

​
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

​
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 (or PUT alias) /api/v1/companies/{companyId}/entities/quote/{entityId} with policyRatingResponse and exposureRatingResponse fields populated. 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