TPP · Insurance · Quotation

Insurance Quotation — API Guide 8 min read

End-to-end walkthrough of the Insurance Quotation flow from the TPP perspective. The flow runs on the Client Credentials Grant — no per-customer consent journey. After accepting a quote, you can subscribe to webhook events to receive status updates without polling. This page covers the subscription mechanism and the full event schema; the per-mode pages walk through the specific call sequences.

01 Two flow variants

Pick the mode you're implementing

LFI-Led

The LFI hosts the customer through completion

Single-PATCH accept flow. Your app collects quote inputs, the LFI hosts everything from acceptance through to issuance. You observe progress via webhook events or polling.

Open →TPP-Led

You collect KYC; the LFI hosts only payment

Two-PATCH flow. You submit KYC, the LFI returns a payment URL via webhook event, you redirect the customer to pay, then deliver documents in your app.

Open →

02 Webhook subscription

Subscribe to events on PATCH Accept Quote

When you PATCH a quote to accept it, you can attach a Subscription.Webhook object to register for event notifications. The Hub will POST status events to your registered URL whenever the LFI emits a quote-log update. Subscribing once on accept covers the entire lifecycle — you do not need to re-subscribe for each status. The webhook delivery surface is documented in Insurance Quote Status Event — API Guide, with the OpenAPI schema at Insurance Quote Status Change Event.

PATCH /motor-insurance-quotes/{QuoteId}json

{
  "Data": {
    "PolicyStartDate": "2026-06-01"
  },
  "Subscription": {
    "Webhook": {
      "Url": "https://tpp.example.ae/webhooks/insurance-quote-events",
      "IsActive": true
    }
  }
}

Subscription object

Field	Type	Required	Description
`Webhook.Url`	string (HTTPS URL)	On first registration	Your HTTPS endpoint that will receive event POSTs. Must match `^https://.+`.
`Webhook.IsActive`	boolean	Always	`true` enables delivery; `false` pauses without removing the URL.

Updating the subscription mid-lifecycle

You can PATCH the quote again at any time with only a Subscription object to update or pause webhook delivery. Omit the Data field; the LFI will not treat this as a re-acceptance.

PATCH (subscription-only)json

{
  "Subscription": {
    "Webhook": {
      "IsActive": false
    }
  }
}

Polling fallback

If you do not register a webhook, poll GET /{type}-insurance-quotes/{QuoteId} to retrieve the current status. Do not exceed one request per minute under normal load — the Hub may rate-limit aggressive polling. Webhooks are strongly preferred.

03 Insurance Quote Event Schema

The three event shapes you must handle

Every event delivered to your webhook conforms to one of three schemas, drawn from the API Hub Consent Manager spec. The QuoteStatus field identifies which schema applies.

1. Pending Completion Status

Sent when the quote is making progress but not yet final. QuoteStatus is one of: ApplicationPending, ApplicationApproved, PaymentRequired, PolicyIssued.

Field	Required	Notes
`QuoteStatus`	Always	One of the pending-completion enum values above.
`BrokerInstructions[]`	When LFI requires TPP action	Each entry: `ActionRequired` (text), `Reason` (text), `Url` (e.g. payment URL).
`Documents[]`	On `PolicyIssued` in TPP-Led mode	Base64-encoded policy documents with SHA-256 hashes. See "Documents" below.

Pending Completion event (ApplicationApproved)json

{
  "QuoteStatus": "ApplicationApproved",
  "BrokerInstructions": [
    {
      "ActionRequired": "Customer must complete premium payment at the LFI-hosted page.",
      "Url": "https://pay.examplelfi.ae/checkout/sess-c93e1f4a"
    }
  ]
}

2. Completed Status

Final event for a successful flow. QuoteStatus: Completed. Carries the finalised premium, policy term, and commission information. No further events follow.

Field	Required	Notes
`QuoteStatus`	Always	Always `"Completed"`.
`PolicyTerm`	Always	ISO 8601 duration, e.g. `P1Y`, `P2Y3M`.
`Premium`	Always	Object with `OneYearPremiumExcludingVAT`, `VATAmount`, `TotalOneYearPremium`, and (optionally) `TotalPolicyPremium`.
`CustomerPaidInFull`	Always	Boolean indicating full payment was received.
`PolicyCountrySubDivision`	Always	UAE Emirate where the policy was issued.
`PolicyStartDate` / `PolicyEndDate`	Recommended	ISO 8601 date.
`CustomerSalary`	Required for Health	`Under4K` or `Over4K` (AED/month).
`Commission`	When TPP commission applies	`CommissionAmount` + `PaymentMethod` (`DirectToTPP` or `ThroughAPIHub`).
`Documents[]`	Optional	Final policy documents if not already delivered on `PolicyIssued`.

Completed Status eventjson

{
  "QuoteStatus": "Completed",
  "PolicyStartDate": "2026-06-01",
  "PolicyEndDate": "2027-05-31",
  "PolicyTerm": "P1Y",
  "Premium": {
    "OneYearPremiumExcludingVAT": { "Currency": "AED", "Amount": "950.00" },
    "VATAmount": { "Currency": "AED", "Amount": "47.50" },
    "TotalOneYearPremium": { "Currency": "AED", "Amount": "997.50" }
  },
  "CustomerPaidInFull": true,
  "PolicyCountrySubDivision": "Dubai",
  "Commission": {
    "CommissionAmount": { "Currency": "AED", "Amount": "47.00" },
    "PaymentMethod": "ThroughAPIHub"
  }
}

3. Terminal Status

Negative terminal events. QuoteStatus is one of: Expired, Rejected, CustomerCancelled, LFICancelled. No further events follow.

Field	Required	Notes
`QuoteStatus`	Always	One of the four terminal enum values.
`Reason`	Optional	Free-text (1–1000 chars) explaining the termination — surface to the customer where helpful.

Terminal Status eventjson

{
  "QuoteStatus": "CustomerCancelled",
  "Reason": "Customer declined payment at the LFI checkout."
}

PolicyIssued with documents (TPP-Led)

PolicyIssued event with Documents[]json

{
  "QuoteStatus": "PolicyIssued",
  "Documents": [
    {
      "Type": "Policy Booklet",
      "FileName": "policy-booklet.pdf",
      "ContentType": "application/pdf",
      "Content": "JVBERi0xLjQKJeLjz9MKMyAwI...",
      "HashType": "SHA256",
      "Hash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
    }
  ]
}

04 Document handling

Verifying and surfacing policy documents

In TPP-Led mode, the PolicyIssued event carries every customer-facing document the LFI would normally deliver itself. Your TPP becomes the document delivery channel — the LFI will not email or post the documents.

Document object

Field	Notes
`Type`	Document category (e.g. "Policy Booklet", "Terms & Conditions", "IPID"). Free-text.
`FileName`	Original file name with extension. No path components.
`ContentType`	One of `application/pdf`, `image/jpeg`, `image/png`.
`Content`	Base64-encoded file bytes.
`HashType`	Always `SHA256`.
`Hash`	SHA-256 of the raw file bytes (decoded `Content`). Required for integrity verification.
`AdditionalInformation`	Optional free text (max 1000 chars).

Verification

Before surfacing a document to the customer, decode Content, compute its SHA-256, and compare against Hash. Mismatches indicate corruption or tampering — do not deliver. Log the x-fapi-interaction-id from the event delivery and raise a support ticket including that ID and the QuoteId.

05 Webhook security

Verify event signatures before acting

Events delivered to your webhook are signed by the Hub. You MUST verify the signature on every event before applying it. See Receiving Event Notifications for the signature scheme.

The Hub may redeliver an event after a transient delivery failure. Treat events as idempotent — apply the latest QuoteStatus for the QuoteId, do not count events. Tracking by QuoteId + QuoteStatus + event timestamp is sufficient to dedupe.

06 Per-quote-type rules

New, Renewal, and Switch differences

The semantic differences between New, Renewal, and Switch — and the per-type field requirements — are documented in the shared Quote Types explainer. Read it before issuing Renewal or Switch quotes; both require referencing a prior policy retrieved through Insurance Data Sharing under a customer consent.