curl --request POST \
--url https://go.aiinsurance.io/api/v1/companies/{companyId}/quotes/{quoteId}/rate \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"ratingWorkflowName": "standard"
}
'{
"data": {
"quoteType": "newBusiness",
"quoteNumber": "Q-000123",
"quoteStatus": "inProgress",
"primaryInsured": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"exposureName": "Acme Co",
"exposureRatingResponse": {
"premium": 1000
}
},
"otherExposures": [
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"exposureName": "Beta LLC",
"exposureRatingResponse": {
"premium": 1000
}
}
],
"fullTermPolicyRatingResult": {
"policyPremium": 3000,
"policyGrandTotal": 3500
}
}
}Rate Saved Quote by Id
Rates a saved quote by id with a named rating workflow and returns the
premium and rating results; send saveToQuote: true to save a successful
rating on the quote,, as the app’s Generate Rating and Save do. To price
quote data that is not saved, or what-if values, use Rate Quote (Read-Only)
(rateQuote). New business, renewal and endorsement quotes can be rated;
cancellation and reinstatement quotes cannot.
Without saveToQuote, the rated field bag remains stateless. No quote
field or rating run is persisted, and the quote row is byte-identical
before and after — same field values, same updatedAt. On a successful
rate, the service records the requested ratingWorkflowName as Quote
system metadata so later saved-quote workflows know which workflow was
selected. A failed rating does not change that selection. The rating
results exist only in the response you receive.
With saveToQuote: true, a successful rating is saved, as the app’s
Generate Rating and Save do. In one transaction the quote gets what the
rating workflow owns — the containers it clears and the fields its stages
write, pricing included — and nothing else, and the save recalculates the
quote’s calculated fields, so fullTermBillingInfo follows the new
pricing. The run is recorded as the quote’s current rating, so
Bind Quote and
Check Bind Conditions
check whether it is out of date as they check a rating saved in the app,
and the workflow selection is recorded. Saving also needs quote.edit; a
bound or cancelled quote returns 409, and so does a quote that changed
while it was being rated (409 quote-changed-during-rating: rate it
again). A failed rating saves nothing. The response is the same either
way.
This is the by-id sibling of
POST /api/v1/companies/{companyId}/quotes/rate; the field-bag difference is
where the field bag comes from — loaded from the saved quote here, supplied
in the request body there. Only the by-id endpoint can record a saved quote’s
workflow selection or save a rating.
The quote id is a path parameter; the request body carries
ratingWorkflowName and saveToQuote. There are deliberately no data
overrides — to rate what-if values (“as if field X were Y”), GET the
quote, tweak it, and POST the full-body /quotes/rate endpoint, which
supports inline overrides.
Semantics. The saved quote’s stored field bag is validated with the
identical create-quote pipeline (shape, resolution, tenant invariants, entity
invariants), embedded exposure id references are looked up and merged from
their stored data exactly as the full-body endpoint does, and then the named
rating workflow runs. A stateless rate has no quote-status gate — for a
supported quote type, any saved quote rates regardless of quoteStatus
(bound and cancelled included), because a rate that saves nothing can
corrupt nothing. This status promise does not expand the supported quote
types: cancellation and reinstatement return a structured
400 InvalidRequest before any rater or vendor call because those
transactions preserve rating and derive or restore pricing.
The 200 response returns the saved quote’s bag under data, enriched with
the rating outputs (e.g. exposureRatingResponse on each exposure and the
full-term policy rating containers).
The response reflects only this run. The rating workflow clears the containers it owns before any rater runs and rebuilds them from this run’s output, so a rate that prices nothing returns those containers empty rather than carrying the quote’s previously stored figures, and saving it clears the stored figures.
Rating failures also return 200 — with a diagnostics array
describing what went wrong and no data. Check for the presence of
data to detect success, not the HTTP status. Invalid requests (anything
under the 400/404/409/422 descriptions below) are still rejected
with their status codes; only failures during rating execution itself
(e.g. a rating vendor error) report as 200 + diagnostics.
Required permission: quote.rate, and quote.edit as well with
saveToQuote: true
curl --request POST \
--url https://go.aiinsurance.io/api/v1/companies/{companyId}/quotes/{quoteId}/rate \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"ratingWorkflowName": "standard"
}
'{
"data": {
"quoteType": "newBusiness",
"quoteNumber": "Q-000123",
"quoteStatus": "inProgress",
"primaryInsured": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"exposureName": "Acme Co",
"exposureRatingResponse": {
"premium": 1000
}
},
"otherExposures": [
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"exposureName": "Beta LLC",
"exposureRatingResponse": {
"premium": 1000
}
}
],
"fullTermPolicyRatingResult": {
"policyPremium": 3000,
"policyGrandTotal": 3500
}
}
}Authorizations
Path Parameters
Body
The configured rating workflow to run. Required in practice —
there is no default even when a single workflow is configured —
but it is not schema-required: rather than a shape rejection, a
missing or unknown name returns a 400 listing the configured
workflow names (and a company with no workflows configured
returns a 422), so callers get an actionable error naming the
valid options. There is no fallback to any per-quote persisted
selection.
"standard"
Response
The rating outcome. A successful rate records the requested workflow
selection; with saveToQuote: true it also saved the rating to the
quote, and otherwise the returned field values are not saved.
Success: data carries the saved quote's bag enriched with rating
outputs.
Rating failure: the response is still 200, with diagnostics
describing what went wrong and no data — the absent data is
the failure signal, so do not treat the presence of diagnostics
alone as failure: severity: warning diagnostics ride alongside a
successful data when a rater reports them. Rating failures are
engine/vendor faults during rating execution; an invalid request is
still a 4xx, and an unexpected application fault is still a 500.