> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Invoke the rating engine or supply external rating results via API

<Note>
  **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](/api-reference/roadmap) for overall API direction.
</Note>

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](#external-rating-bring-your-own-engine) 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

| Method | Endpoint                                              | Description                                                                                                  |
| ------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| POST   | `/api/v1/companies/{companyId}/quotes/rate`           | **Stateless** — rate the quote a create-quote body would create and return the results; nothing is persisted |
| POST   | `/api/v1/companies/{companyId}/quotes/{quoteId}/rate` | **Stateless** — rate an already-saved quote by id and return the results; the quote is never modified        |

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

| Method | Endpoint                                     | Description                                        |
| ------ | -------------------------------------------- | -------------------------------------------------- |
| POST   | `/v1/policies/{policyId}/rating/endorsement` | Rate an endorsement (a set of deltas) for a policy |

### 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](#external-rating-bring-your-own-engine) 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

| Operation                                            | Permission                                            |
| ---------------------------------------------------- | ----------------------------------------------------- |
| Rate a quote statelessly — by body or by id (hosted) | `company.quote:rate`                                  |
| Rate an endorsement (hosted)                         | *Planned* — not yet exposed via the external API      |
| Update a quote (external rating)                     | `company.policy:create` (the Quote update permission) |

## Related Resources

* [Entities API](/api-reference/entities/overview) — create and manage quotes
* [Policy API](/api-reference/policies/overview) — create policies from rated quotes via the transaction model
* [Roadmap](/api-reference/roadmap) — overall API direction