TPP · Insurance · Quotation · LFI-Led

LFI-Led Flow 6 min read

You collect quote inputs in your app and hand the customer to the LFI on accept. The LFI hosts customer verification, payment, and document delivery. Your role after acceptance is to observe status events — either via webhook subscription or polling — and surface progress to the customer.

01 End-to-end sequence

LFI-Led flow

Sequence diagramInsurance Quotation — LFI-Led FlowClick to expand

02 Step 1 — Client credentials

Obtain an access token

Authenticate with the Client Credentials Grant using a signed client assertion. Request the insurance scope.

POST /tokenhttp

POST /token HTTP/1.1
Host: as1.[LFICODE].apihub.openfinance.ae
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=insurance
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsImtpZCI6...

The returned access_token is valid for all Insurance Quotation calls until expiry. There is no per-customer token in this flow.

03 Step 2 — POST /{type}-insurance-quotes

Request a quote

Send the quote request as an application/jwt signed Request JWT. The body carries a QuoteReference you generate (for your own tracking), a QuoteType of New, Renewal, or Switch, and sector-specific risk and policy holder data.

POST /motor-insurance-quotes (decoded JWT body)json

{
  "Data": {
    "QuoteReference": "tpp-ref-2026-04-001",
    "QuoteType": "New",
    "Policy": {
      "StartDate": "2026-06-01",
      "Term": "P1Y"
    },
    "Vehicle": {
      "RegistrationNumber": "A 12345",
      "Emirate": "Dubai",
      "Make": "Toyota",
      "Model": "Camry",
      "YearOfManufacture": 2022
    },
    "PolicyHolder": {
      "EmiratesId": "784-1990-XXXXXXX-X",
      "DateOfBirth": "1990-05-12"
    }
  }
}

The LFI returns 201 with one or more quotes, or 204 if it declines to quote. Each entry includes a QuoteId (LFI-minted) you use for subsequent calls.

201 responsejson

{
  "data": [
    {
      "QuoteStatus": "Available",
      "QuoteId": "8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e",
      "QuoteReference": "tpp-ref-2026-04-001",
      "CreationDateTime": "2026-04-18T10:14:23Z",
      "ExpirationDateTime": "2026-05-18T10:14:23Z",
      "PlanName": "Comprehensive Plus",
      "PolicyIssuanceAllowed": {
        "CustomerVerification": false,
        "Payment": false,
        "PolicyDocuments": false
      },
      "Premium": {
        "TotalOneYearPremium": { "Currency": "AED", "Amount": "997.50" }
      }
    }
  ]
}

QuoteId vs QuoteReference

QuoteId is the LFI’s identifier — required for every subsequent call. QuoteReference is your own tracking identifier, echoed back by the LFI so you can correlate quotes to your internal session. Persist both.

04 Step 3 — PATCH Accept Quote

Accept and subscribe to events

Customer picks a quote in your UI. PATCH the chosen QuoteId with the accept data and a Subscription.Webhook object if you want event notifications. Send as a signed application/jwt.

PATCH /motor-insurance-quotes/{QuoteId} (decoded)json

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

In LFI-Led mode the LFI responds 204 No Content. The customer is now in the LFI’s hosted journey. Your app should surface a "your application is being processed" state and wait for the first event.

05 Step 4 — Customer handoff

Redirect the customer to the LFI

The mechanism for handing the customer off depends on the LFI — typically a hosted application URL returned at quote creation time or out-of-band. From this point until the PolicyIssued event, the customer interacts with the LFI’s screens, not yours.

Your app receives ApplicationPending (and any interim status updates the LFI emits) through the webhook. Surface them in the customer’s timeline so they can re-enter your app and see where their application has reached.

06 Step 5 — Receive lifecycle events

Handle the status sequence

Events arrive at your webhook in this typical order:

ApplicationPending — LFI has registered the application.
(optional intermediate events with BrokerInstructions) — LFI surfacing status the customer needs to see.
PolicyIssued — carries the InsurancePolicyId.
Completed — finalised premium, term, and commission. Terminal event.

Verify each event’s signature and dedupe by QuoteId. The PolicyIssued event in LFI-Led mode carries only InsurancePolicyId — the LFI has delivered the policy documents directly to the customer through its hosted journey.

PolicyIssued event (LFI-Led)json

{
  "QuoteStatus": "PolicyIssued",
  "InsurancePolicyId": "pol-2026-000457"
}

07 Step 6 — POST /{type}-insurance-policies

Issue the policy

After the customer has progressed through the LFI’s hosted KYC and payment, your app calls POST to formally create the policy resource. In LFI-Led mode the body is minimal — just the QuoteId. The LFI runs its issuance and responds 201 Created.

The final InsurancePolicyId arrives via the PolicyIssued webhook event, not in this response body. Retries are safe: the LFI is required to return the same policy reference for the same QuoteId.

08 Step 7 — Completed

Surface the final policy to the customer

On the Completed event, finalise the customer-facing timeline: policy is live, documents are with the customer (delivered by the LFI), and any commission owed is being processed via Commission.PaymentMethod.

Manage subscription lifecycle in your own systems — you can let the subscription lapse (it’s tied to the QuoteId) or PATCH with IsActive: false if you explicitly want to stop delivery (for example, before deprovisioning a webhook URL).