Insurance Data Sharing — API Guide 5 min read
How your Ozone Connect server receives, processes, and responds to Insurance Data Sharing requests proxied by the API Hub. The end-to-end flow — consent validation, authorisation, token issuance — is identical to Bank Data Sharing; this page focuses on the insurance-specific differences.
What you implement on Ozone Connect
For Insurance Data Sharing, your LFI implements one pair of endpoints per insurance sector you underwrite on your Ozone Connect server:
| Endpoint | Purpose |
|---|---|
GET/{type}-insurance-policies | Return every policy of the named sector the consent grants access to. |
GET/{type}-insurance-policies/{InsurancePolicyId} | Return the single policy identified by the path parameter, after checking it belongs to the consented customer. |
Substitute the sector slug (employment, health, home, life, motor, renters, travel) for {type}. Implement only the sectors your LFI underwrites — the API Hub will not route requests for unmounted sectors.
Same validate hook as Bank Data Sharing
During consent creation, if your LFI has configured the POST/consent/action/validate endpoint, the API Hub forwards the full insurance consent payload to your Ozone Connect server before the consent is created. For Insurance Data Sharing consents, consentType is cbuae-insurance-consents.
The mechanics are identical to Bank Data Sharing — respond with data.status: valid to allow the consent, or invalid with an error if the requested permissions cannot be granted. See the Consent Journey API Guide — Validate the consent for the request and response shapes.
Authorize the customer at your LFI
Once the consent has been created, the TPP redirects the customer to your LFI’s authorisation endpoint — the same URL you registered for Bank Data Sharing. From there, your LFI runs the standard consent journey: authenticate the customer, retrieve the consent, let the customer approve or reject it, patch the customer identifier onto the consent, and redirect back to the Hub.
The endpoints your LFI implements against the API Hub for this flow are the same as Bank Data Sharing — see Bank Data Sharing — Consent flow for the full list. The only difference for insurance is that there are no per-account identifiers to patch; the consent is granted at the policy-collection level per sector, and the Hub forwards each policy lookup directly to your endpoints.
Shared conventions
Field population
Every field that exists on the LFI’s systems, or is derivable from them, MUST be populated in the response. TPPs rely on this data to serve customer use cases end-to-end — a field omitted by the LFI is a feature the TPP cannot build.
Common request headers
Insurance endpoints receive the same set of o3-* headers from the API Hub as Bank Data Sharing. See Common request headers for the full table.
No pagination
Insurance policy endpoints return the full set of consented policies for the named sector in a single response. There is no page query parameter, and Meta does not carry TotalPages or TotalRecords. If the consent grants access to twelve motor policies, your /motor-insurance-policies response MUST contain all twelve.
Error responses
Use the same UAE Open Finance error envelope and HTTP status codes as Bank Data Sharing. 404 for an InsurancePolicyId the consent does not grant access to. 403 if the policy exists but is not in a state your LFI surfaces (e.g. cancelled and outside the retention window). The Hub validates token, consent, and TPP role before the request reaches your endpoint; you do not re-validate any of those.
Return all consented policies for a sector
/{type}-insurance-policies Return every active policy of the named sector the consent grants access to. Each Policy entry MUST include the fields required by the OpenAPI spec for that sector, plus every optional field your LFI holds.
Required permission
The Hub only routes the request to your endpoint if the consent contains ReadInsurancePolicies for the named sector. You do not need to re-check the permission.
Example response
{
"Data": {
"Policy": [
{
"InsurancePolicyId": "policy-001",
"PolicyNumber": "MTR-2025-000123",
"PolicyStatus": "Active",
"InceptionDate": "2025-01-15",
"RenewalDate": "2026-01-14",
"Insurer": { "Name": "Example Insurance LLC" },
"Premium": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2R0NN..."
}
]
},
"Links": {
"Self": "https://ozone-connect.example.ae/motor-insurance-policies"
},
"Meta": {}
}
Return a single policy
/{type}-insurance-policies/{InsurancePolicyId} Return the single policy identified by InsurancePolicyId. The InsurancePolicyId MUST belong to a policy your LFI underwrites for the customer identified by the o3-psu-identifier header — if it does not, respond with 404.
Example response
{
"Data": {
"Policy": {
"InsurancePolicyId": "policy-001",
"PolicyNumber": "MTR-2025-000123",
"PolicyStatus": "Active",
"Insurer": { "Name": "Example Insurance LLC" },
"Premium": {
"PremiumAmountExcludingVAT": "950.00",
"PremiumVATAmount": "47.50",
"TotalPremiumAmount": "997.50",
"Currency": "AED",
"PremiumFrequency": "Annually"
}
}
},
"Meta": {}
}