Draft

This is v2.2-draft — a working draft of the v2.2 standards, published for review and not yet ratified. It MUST NOT be used as the basis for a production implementation. For the current standards, switch to v2.1 using the version selector. See the v2.1 → v2.2-draft changelog for every change in this version.

Validate · Enforce · Trust

Insurance Quotation — Requirements v2.2-draft12 min read

The validation rules that apply to Insurance Quotation. The Validated by column on each table indicates where each rule is enforced. Insurance Quotation does not use a per-customer consent — TPPs authenticate with the Client Credentials Grant and act as themselves throughout the quote lifecycle. Read alongside the API Guide and User Journeys.

All requests require an active Trust Framework application with the ISP role, a valid transport certificate presented on every request via mTLS, an active signing key for JWT signing, and a client credentials access token with the insurance scope.

01 Endpoint

Create a Quote

POST/{type}-insurance-quotes

Field

Rule

Validated by

Sector slug in path

Must be one of employment, health, home, life, motor, renters, or travel. The Hub returns 404 for any other value before the request reaches the LFI.

API Hub

QuoteType

Must be one of New, Renewal, or Switch. See Quote Types for the per-type field requirements (Renewal references the prior policy; Switch references the incumbent insurer).

API Hub (schema) + LFI (logic)

Quote request body

Must conform exactly to the per-sector quote request schema in the OpenAPI spec. Sector-specific identifiers (e.g. Vehicle for Motor, PropertyAddress for Home, TripDetails for Travel) are required.

API Hub

Customer identifiers

Customer identification fields (Emirates ID, date of birth, etc.) carried inline on the quote request are subject to the same data-minimisation rules as other Open Finance flows — only collect what is required to underwrite. There is no JWE encryption for Insurance Quotation PII.

TPP discretion

Access token

Must be a Client Credentials Grant token issued by the API Hub authorisation server with the insurance scope. Customer consent tokens (Authorization Code Grant) MUST NOT be used.

API Hub

Signed request

The request body MUST be sent as an application/jwt Request JWT signed with the TPP's signing key, per the FAPI security profile. Unsigned requests are rejected with 400.

API Hub

x-fapi-interaction-id

Should be included. Should be a valid UUID (RFC 4122). An invalid value will not cause a failure but tracing will not be possible.

N/A

Response — 201

The LFI returned one or more quotes. Each entry includes a QuoteId the TPP uses for retrieval, acceptance, and policy creation. The TPP MUST persist the QuoteId alongside the customer context.

TPP

Response — 204

The LFI declined to quote (e.g. risk profile out of appetite). The TPP MUST surface the decline to the customer without retrying.

TPP

02 Endpoint

Retrieve a Quote

GET/{type}-insurance-quotes/{QuoteId}

Field

Rule

Validated by

QuoteId

Must be a QuoteId the TPP previously received from this LFI's POST /{type}-insurance-quotes response, in the matching sector. An unknown or cross-sector ID returns 404.

LFI

Quote ownership

The LFI returns 404 rather than 403 if the QuoteId belongs to a different TPP, to prevent leakage of quote existence.

LFI

03 Endpoint

Accept a Quote (and Subscribe to Events)

PATCH/{type}-insurance-quotes/{QuoteId}

Field

Rule

Validated by

Data

Carries the accept-quote properties for the sector (sector-specific fields such as policy start date, beneficiary list, etc.). Required when accepting the quote; may be omitted on subsequent PATCHes that only manage the webhook subscription.

API Hub + LFI

Subscription.Webhook.Url

Optional. If the TPP wants to receive event notifications, set Url to an HTTPS endpoint the TPP controls. The URL MUST match ^https://.+. The Hub will POST status events to this URL for the lifetime of the quote (see API Guide). If omitted, the TPP must poll via GET /{type}-insurance-quotes/{QuoteId}.

API Hub

Subscription.Webhook.IsActive

Required when Subscription is present. true activates webhook delivery; false pauses it without removing the registered URL. The TPP can PATCH later with IsActive: false to disable webhooks mid-lifecycle without altering the quote.

API Hub

Signed request

PATCH body MUST be sent as application/jwt signed with the TPP's signing key.

API Hub

Response — 200 (TPP-Led)

The LFI returns data.PolicyIssuanceAllowed declaring which steps the TPP may perform: CustomerVerification, Payment, PolicyDocuments. The TPP MUST honour these flags — only perform the steps the LFI has explicitly allowed.

TPP

Response — 204 (LFI-Led)

The LFI has accepted the quote and will drive the application internally. The TPP's next step is to wait for the ApplicationPending → PolicyIssued → Completed event sequence (via webhook or polling).

TPP

04 Endpoint

Submit KYC (TPP-Led only)

PATCH/{type}-insurance-quotes/{QuoteId}

Field

Rule

Validated by

Eligibility

Submit KYC is only valid in TPP-Led mode (i.e. the Accept Quote response carried PolicyIssuanceAllowed.CustomerVerification: true). Calling it for an LFI-Led quote results in 409.

LFI

KYC payload

Must conform to the sector's accept-quote / KYC request schema. The TPP is responsible for collecting valid customer identification (Emirates ID, etc.) and forwarding it verbatim.

API Hub + LFI

Customer presence

The TPP MUST collect the KYC data with the customer present and consenting — this submission acts as the customer's instruction to proceed with the application.

TPP

05 Section

Event Subscription and Handling

Field

Rule

Validated by

Webhook endpoint

Must be reachable over HTTPS with a valid TLS certificate. The Hub will not deliver events to plaintext, self-signed, or expired endpoints.

API Hubdelivery

Webhook authentication

Events are signed by the Hub. The TPP MUST verify the signature on every received event before acting on it — see Receiving Event Notifications.

TPP

Idempotency

The Hub may redeliver an event after a transient delivery failure. The TPP MUST treat events as idempotent — apply the latest QuoteStatus rather than counting events. Tracking by QuoteId + QuoteStatus + event timestamp is sufficient.

TPP

Status vocabulary

Events carry one of three schemas: pending-completion (ApplicationPending, ApplicationApproved, PaymentRequired, PolicyIssued), completed (Completed), or terminal (Expired, Rejected, CustomerCancelled, LFICancelled). The TPP MUST handle all three.

TPP

BrokerInstructions.Url

When emitted on ApplicationApproved or PaymentRequired, this is the LFI-hosted URL the TPP MUST redirect the customer to in order to complete payment. The URL is single-use and time-bound. The TPP MUST NOT scrape, modify, or replay it.

TPP

Documents

When emitted on PolicyIssued in TPP-Led mode, the TPP MUST verify each document's SHA-256 Hash against the decoded Content, then make the documents available to the customer (download, email, in-app viewer). The TPP becomes the policy document delivery channel.

TPP

Polling fallback

TPPs without a webhook subscription MUST poll GET /{type}-insurance-quotes/{QuoteId} at a reasonable cadence (no more than once per minute under normal load). The Hub may rate-limit aggressive polling.

TPP

06 Endpoint

Create a Policy

POST/{type}-insurance-policies

Field

Rule

Validated by

QuoteId

The body MUST reference a QuoteId the TPP previously accepted at this LFI, in the matching sector. A mismatched sector or unknown QuoteId returns 404.

LFI

TPP-supplied data (TPP-Led)

For TPP-Led quotes where the TPP collected KYC, the body carries that KYC plus any additional data the LFI requires. For LFI-Led quotes the body may be empty beyond the QuoteId.

LFI

Signed request

POST body MUST be sent as application/jwt signed with the TPP's signing key.

API Hub

Idempotency

If the TPP retries POST Create Policy with the same QuoteId after a successful response, the LFI MUST return the same policy reference rather than minting a duplicate. The TPP SHOULD use the x-fapi-interaction-id to correlate retries.

LFI

Response — 201

The LFI has accepted the policy creation request. The TPP awaits the PolicyIssued → Completed event sequence (or polls). The final InsurancePolicyId and the Documents arrive via the quote-log events, not in this response body.

TPP