Insurance Quotation — Requirements v2.112 min read
The Insurance Quotation flow runs on the Client Credentials Grant — there is no per-customer consent. TPPs authenticate as themselves, request a quote, and (where the customer accepts) drive the application through to policy issuance. Your Ozone Connect endpoints execute the quote and policy lifecycle; status updates flow back to subscribed TPPs through the Hub.
The tables below list the rules that apply to Insurance Quotation. All request validation of the TPP's credentials, access token, and OpenAPI schema is performed by the Hub before your Ozone Connect endpoints are called. The rules below cover what your Ozone Connect endpoints must validate and what they must return, and what your LFI must emit through the PATCH /insurance-quote-log/{logId} callback to keep the Hub and any subscribed TPP webhooks in sync.
Create Quote
/{type}-insurance-quotesWhen a TPP requests a quote, the Hub validates the access token and OpenAPI schema, then proxies the request to your Ozone Connect POST /{type}-insurance-quotes endpoint with the sector slug (employment, health, home, life, motor, renters, or travel) baked into the path. Your endpoint receives the customer's quote request and either returns one-or-more quotes (201) or declines to quote (204).
404. Only mount endpoints for sectors you actually offer; the Hub will not route requests for unmounted sectors.QuoteType of New, Renewal, or Switch. See Quote Types for the per-type validation differences (e.g. Renewal references a prior policy, Switch references an incumbent insurer). If the requested QuoteType cannot be supported for the sector (e.g. the LFI does not support switching for Travel), return 204 with an empty body.201 response carries a data array of one-or-more quotes. Each entry must include a unique QuoteId the LFI generates and persists — the TPP uses this ID to retrieve, accept, or reject the quote. Populate every field marked required by the per-sector quote schema.204 with an empty body. Do not return a 201 with an empty data array.QuoteId MUST remain retrievable and acceptable for the validity period the LFI advertises on the quote (typically 14–30 days). After expiry, retrievals MUST still return the quote in a Expired terminal state via the quote-log rather than 404 — TPPs need to be able to display an expiry reason.Subscription object on the request body is the TPP's webhook configuration. It is consumed by the Hub for event delivery — the LFI MUST NOT act on it. The LFI's only obligation is to emit status events via PATCH /insurance-quote-log/{logId}; the Hub fans those out to any subscribed TPP webhook.Retrieve Quote
/{type}-insurance-quotes/{QuoteId}QuoteId was created in response to a request from the same TPP (identified by the Hub via o3-caller-client-id). If the quote belongs to a different TPP, return 404 — do not leak quote existence across TPPs.QuoteId requested via /home-insurance-quotes/{QuoteId} MUST return 404.Accepted into the application lifecycle, include the latest QuoteStatus drawn from the same vocabulary the LFI emits on the quote-log (see Status Updates).Accept Quote
/{type}-insurance-quotes/{QuoteId}The TPP calls PATCH on the quote to indicate the customer has accepted, kicking off the application lifecycle. The response declares PolicyIssuanceAllowed — the steps the LFI permits the TPP to handle (TPP-Led mode) or retains for itself (LFI-Led mode). This declaration drives whether the TPP collects KYC, hosts payment, and issues policy documents, or whether your LFI does.
QuoteId was created in response to a request from the same TPP. Reject with 404 otherwise — do not return 403 (which would confirm the quote exists).Accepted, reject with 409. The TPP should retrieve the quote to see its current state.204 with no body. The TPP knows the quote has been accepted and will await status updates emitted through the quote-log.200 with data.PolicyIssuanceAllowed set to the steps the TPP may perform: CustomerVerification, Payment, and PolicyDocuments. All three booleans are required. Where the TPP hosts payment, the LFI MUST emit a PaymentRequired or ApplicationApproved event with a BrokerInstructions[].Url that the TPP redirects the customer to (see Status Updates).Subscription object is the TPP's webhook registration for the Hub's event delivery. The Hub stores it; the LFI MUST NOT act on it. Your only obligation is to emit status events through PATCH /insurance-quote-log/{logId} and the Hub fans them out.200 or 204 to the PATCH, the LFI MUST PATCH the quote-log with QuoteStatus: ApplicationPending so the TPP — whether polling or subscribed — sees a consistent first status. This is the entry point to the application lifecycle.Create Policy
/{type}-insurance-policiesAfter the application has been progressed (KYC collected, payment confirmed where the TPP hosts it), the TPP calls POST /{type}-insurance-policies with the originating QuoteId and any data the LFI requires to finalise issuance. The LFI runs its BAU policy creation flow.
QuoteId bindingQuoteId that this TPP previously accepted at this LFI under the same sector. If the quote is not in a state that permits policy issuance (e.g. application has not reached ApplicationApproved on TPP-Led, or the quote is terminal), reject with 409.404.400 and explain via errorCode / errorMessage.POST /{type}-insurance-policies against the same QuoteId has already produced a policy, return the existing policy reference rather than minting a new one. Repeated calls with the same payload MUST be safe.PolicyIssued with the issued InsurancePolicyId (LFI-Led) or with Documents attached (TPP-Led) — and then to Completed once any post-issuance work has settled. See Status Updates.Status Updates (Quote Log)
/insurance-quote-log/{logId}The quote lifecycle is observable to TPPs through events the LFI emits to the Hub. The LFI PATCHes /insurance-quote-log/{logId} with the new QuoteStatus; the Hub records it and, where the TPP has subscribed via the Subscription object on the original PATCH Accept Quote, delivers an event to the TPP's webhook. logId is the same value as the QuoteId. The event body conforms to one of three schemas drawn from the Hub spec — terminal, pending-completion, or completed.
ApplicationPendingApplicationApprovedBrokerInstructions array containing a Url (the LFI-hosted payment page) for the TPP to redirect the customer to.PaymentRequiredBrokerInstructions with the payment URL.PolicyIssuedInsurancePolicyId. On TPP-Led, attach the policy Documents (Policy Booklet, Terms & Conditions, etc.) as base64 with SHA-256 hashes so the TPP can verify integrity and surface them to the customer.CompletedPremium breakdown, PolicyTerm, PolicyStartDate/PolicyEndDate, CustomerPaidInFull, PolicyCountrySubDivision, and (where applicable) the Commission due to the TPP. No further events follow.Expired / Rejected / CustomerCancelled / LFICancelledReason where possible. No further events follow.ApplicationPending → (optional ApplicationApproved / PaymentRequired) → PolicyIssued → Completed. Any negative terminal status (Expired, Rejected, CustomerCancelled, LFICancelled) may be emitted from any non-terminal state.Completed or any negative terminal) has been emitted, the LFI MUST NOT emit any further events for that logId. Subsequent PATCHes will be rejected by the Hub with 400.ApplicationApproved or PaymentRequired in TPP-Led mode where the TPP is to host the customer through payment, the BrokerInstructions[].Url MUST be an HTTPS URL the customer can be redirected to. The URL is single-use and tied to the application; the LFI MUST invalidate it after first redemption or after a reasonable session window.PolicyIssued in TPP-Led mode, all documents that would normally be delivered to the customer (Policy Booklet, Terms & Conditions, IPID, etc.) MUST be attached as base64-encoded Documents entries with matching SHA-256 hashes. The TPP becomes the document delivery channel — the LFI MUST NOT email or post them separately.PATCH /insurance-quote-log/{logId} as fire-and-forget from the LFI's perspective once a 204 is returned. If the Hub responds with 4xx or 5xx, the LFI MUST retry with exponential backoff. Lost events leave subscribed TPPs blind to the lifecycle and MUST NOT be tolerated.QuoteId Stewardship
The QuoteId is the single identifier that threads the entire lifecycle — quote retrieval, acceptance, policy creation, and every status update emitted to the quote-log. The LFI is the sole authority for minting QuoteId values.
QuoteId MUST be globally unique within the LFI. UUIDv4 is recommended.QuoteId for the policy retention period applicable to the sector (typically aligned with the five-year retention floor that applies to issued policies). The QuoteId MUST remain retrievable via GET /{type}-insurance-quotes/{QuoteId} even in terminal states for the lifetime of any policy that may have been issued from it.QuoteId belongs to a single sector and is not transferable. The same UUID MUST NOT be re-issued for a different sector.QuoteId belongs to the TPP that created it. Any GET, PATCH, or POST referencing it MUST verify ownership via o3-caller-client-id before responding.