Versions Compared

Version Old Version 1 New Version Current
Changes made by

Chris Michael

Chris Wood

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The OFP MUST return an API response when provided with a valid access token request from the TPP.

2. Sequence Diagram

The flows illustrate the API interactions completing successfully, with no API Errors.

...

All sequence diagrams relating to Insurance are now available in the API Hub Documentation.

3. Examples

The following are non-normative examples of API access and usage of the Insurance Information API.

...

Code Block
{
    "typ": "JWT",
    "alg": "PS256",
    "kid": "e4ce77c498e77000a25aa7b40e4a83f9"
}
.
{
    "iss": "s6BhdRkqt3",
    "aud": "https://server.example.com",
    "response_type": "code",
    "redirect_uri": "https://openbanking.tpp1.ae/simple-redirect-url",
    "scope": "insurance",
    "state": "2616df22-899e-468b-b7af-927145b067cc",
    "authorization_details": [
        {
            "Type": "urn:openfinanceuae:insurance-consent:v1.0-draft3rc1",
            "Consent": {
                "ConsentId": "6a6a826f-0930-4eb0-b365-a8eac3032828",
                "Permissions": [
                    "ReadMotorInsurancePolicies",
                 "ReadInsurancePoliciesMotor   "ReadMotorInsuranceCustomerBasic",
                    "ReadMotorInsuranceCustomerPaymentDetails"
                ],
                "ExpirationDateTime": "2024-03-28T15:27:13+030",
                "Purpose": [
                    "MotorInsuranceQuote"
                ]
            }
        }
    ]
}

...

Code Block
GET /open-finance/insurance/v1.0-draft3rc1/insurance-policies HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

...

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
    "Data": [
      {
        "PolicyTypeInsurancePolicyId": "Motor176794ea-ee8c-4621-b824-b8cfa95db0ff",
        "PolicyDetailsPolicyType": {
"Motor",
         "InsurancePolicyIdCustomer": "176794ea-ee8c-4621-b824-b8cfa95db0ff",{
          "CustomerId": "dcaaef9c-63cb-4c57-9f2a-a4986c4a958e",
          "PolicyReferenceFullName": "9e77ccbd-f3c0-4a51-8c22-48c51531a4deHamad Ali",
          "PolicyHolderNamePrimaryLanguage": "HamadEnglish"
Ali",        }
  "CustomerCommunicationDetails": {   }
    ],
    "CorrespondenceAddressLinks": {
              "AddressLine": [
                "PO Box 12345"
              ],
       "Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-rc1/insurance-policies"
    },
      "PostalCodeMeta": "12345",
 {
            "City"TotalPages": "Al Qouz1",
    }
         "StateEmirate": "Dubai",
              "Country": "UAE"
            }}

3.8 Get an Insurance Policy

3.8.1 Request: Insurance Policy Resource

Code Block
GET /open-finance/insurance/v1.0-rc1/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.8.2 Response: Insurance Policy Resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "Data": {
    "InsurancePolicyId": "176794ea-ee8c-4621-b824-b8cfa95db0ff",
    "PolicyType": "Motor",
      "PermanentAddressCustomer": {
      "CustomerId": "dcaaef9c-63cb-4c57-9f2a-a4986c4a958e",
      "AddressLineFullName": ["Hamad Ali",
               "PO Box 12345"PrimaryLanguage": "English"
    }
         ]},
        "Links": {
     "PostalCode": "12345",
              "City": "Al Qouz",
              "StateEmirate": "Dubai",
              "Country": "UAE"
            },
            "ResidentialAddress": {
              "AddressLine": [
                "PO Box 12345"
              ],
              "PostalCode": "12345",
              "City": "Al Qouz",
              "StateEmirate": "Dubai",
              "Country": "UAE"
            },
            "CommunicationPreferences": [
              {
                "Type": "Home",
                "PhoneNumber": "971000000000"
              }
            ],
            "Email": "hamad.ali@email.ae"
          },
          "IndividualCustomerDetails": {
            "Gender": "Male",
            "DateofBirth": "2003-09-12",
            "MaritalStatus": "Married",
            "Nationality": "UAE",
            "NumberofChildren": 1
          },
          "VehicleInformation": {
            "CarMake": "Toyota",
            "CarModel": "Land Cruiser",
            "CarModelYear": "2023",
            "CarPurchaseDateTime": "2023-01-31T00:00:00.000Z",
            "EstimatedValueAmount": {
              "Currency": "AED",
              "Amount": 180000
            },
            "RegistrationDateTime": "2023-01-31T00:00:00.000Z",
            "CountryofOrigin": "ARE",
            "VehicleColor": "White",
            "PlateNumber": "12345",
            "PlateCode": "1",
            "VehicleMileage": 50000,
            "VehicleWeight": 2000,
            "VehicleHistory": "Imported"
          },
          "InsurancePolicyInformation": {
            "IssueDateTime": "2024-05-01T00:00:00.000Z",
            "ExpiryDateTime": "2025-04-31T23:59:59.999Z",
            "PolicyType": "Comprehensive",
            "CoverageAmount": {
              "Currency": "AED",
              "Amount": 180000
            },
            "CoverageStartDateTime": "2024-05-01T00:00:00.000Z",
            "PolicyPremium": {
              "Currency": "AED",
              "Amount": 4600
            },
            "PolicyHolderEmirates": true,
            "PreviousPolicy": {
              "PolicyReference": "8a43bab5-43d8-4525-b92d-840eff449ba5",
              "Insurer": "AXA",
              "PolicyStartDateTime": "2023-05-01T00:00:00.000Z",
              "PolicyExpiryDateTime": "2024-04-31T23:59:59.999Z"
            }
          },
          "AddOns": {
            "DriversPersonalAccident": true,
            "PassengersPersonalAccident": true
          },
          "AdditionalInformation": {
            "FirstTimeRegistration": "true",
            "VehicleMortgageAmount": {
              "Currency": "AED",
              "Amount": 180000
            }
          }
        }
      }
    ],
    "Links": {
      "Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-draft3/insurance-policies"
    },
    "Meta": {
      "TotalPages": "1"
    }
  }

3.8 Get an Insurance Policy

3.8.1 Request: Insurance Policy Resource

Code Block
GET /open-finance/insurance/v1.0-draft3/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.8.2 Response: Insurance Policy Resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
    "Data": {
      "PolicyType": "Motor",
      "PolicyDetails": {
        "InsurancePolicyId": "176794ea-ee8c-4621-b824-b8cfa95db0ff",
        "CustomerId": "dcaaef9c-63cb-4c57-9f2a-a4986c4a958e",
        "PolicyHolderName": "Hamad Ali",
        "CustomerCommunicationDetails": {
          "CorrespondenceAddress": {
            "AddressLine": [
              "PO Box 12345"
            ],
            "PostalCode": "12345",
            "City": "Al Qouz",
            "StateEmirate": "Dubai",
            "Country": "UAE"
          },
          "PermanentAddress": {
            "AddressLine": [
              "PO Box 12345"
            ],
            "PostalCode": "12345",
            "City": "Al Qouz",
            "StateEmirate": "Dubai",
            "Country": "UAE"
          },
          "ResidentialAddress": {
            "AddressLine": [
              "PO Box 12345"
            ],
            "PostalCode": "12345",
            "City": "Al Qouz",
            "StateEmirate": "Dubai",
            "Country": "UAE"
          },
          "CommunicationPreferences": [
            {
              "Type": "Home",
              "PhoneNumber": "971000000000"
            }
          ],
          "Email": "hamad.ali@email.ae"
        },
        "IndividualCustomerDetails": {
          "Gender": "Male",
          "DateofBirth": "2003-09-12",
          "MaritalStatus": "Married",
          "Nationality": "UAE",
          "NumberofChildren": 1
        },
        "VehicleInformation": {
          "CarMake": "Toyota",
          "CarModel": "Land Cruiser",
          "CarModelYear": "2023",
          "CarPurchaseDateTime": "2023-01-31T00:00:00.000Z",
          "EstimatedValueAmount": {
            "Currency": "AED",
            "Amount": 180000
          },
          "RegistrationDateTime": "2023-01-31T00:00:00.000Z",
          "CountryofOrigin": "ARE",
          "VehicleColor": "White",
          "PlateNumber": "12345",
          "PlateCode": "1",
          "VehicleMileage": 50000,
          "VehicleWeight": 2000,
          "VehicleHistory": "Imported"
        },
        "InsurancePolicyInformation": {
          "IssueDateTime": "2024-05-01T00:00:00.000Z",
          "ExpiryDateTime": "2025-04-31T23:59:59.999Z",
          "PolicyType": "Comprehensive",
          "CoverageAmount": {
            "Currency": "AED",
            "Amount": 180000
          },
          "CoverageStartDateTime": "2024-05-01T00:00:00.000Z",
          "PolicyPremium": {
            "Currency": "AED",
            "Amount": 4600
          },
          "PolicyHolderEmirates": true,
          "PreviousPolicy": {
            "PolicyReference": "8a43bab5-43d8-4525-b92d-840eff449ba5",
            "Insurer": "AXA",
            "PolicyStartDateTime": "2023-05-01T00:00:00.000Z",
            "PolicyExpiryDateTime": "2024-04-31T23:59:59.999Z"
          }
        },
        "AddOns": {
          "DriversPersonalAccident": true,
          "PassengersPersonalAccident": true
        },
        "AdditionalInformation": {
          "FirstTimeRegistration": "true",
          "VehicleMortgageAmount": {
            "Currency": "AED",
            "Amount": 180000
          }
        }
      }
    },
 Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-rc1/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff"
  }
}

3.9 Get Customer Payment Details

3.9.1 Request: Customer Payment Details Resource

Code Block
GET /open-finance/insurance/v1.0-rc1/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff/customer-payment-details HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.9.2 Response: Customer Payment Details Resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d
{
  "Data": {
    "SchemeName": "IBAN",
    "Identification": "SA4420000001234567891234",
    "Name": "Mr Hamad Ali"
  },
  "Links": {

     "Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-draft3rc1/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff"
 /customer-payment-details"
  }
  }

4. Further Examples

4.1 The TPP Queries the Insurance Resource for the Status after a User has Authorized the Consent

...

Code Block
GET /open-finance/insurance/v1.0-draft3rc1/insurance-consents/aac-1a672e83-d1e5-42bc-b8e1-60a490ec52fd HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/json
x-fapi-interaction-id: 2e974f01-d111-4078-9a19-7a9b385e637c
Authorization: Bearer e6156449-6f27-4c42-aa5b-36602f73eac9

...

Code Block
HTTP/1.1 200 OK
Content-Type:application/json
x-fapi-interaction-id: 2e974f01-d111-4078-9a19-7a9b385e637c
{
  "Data": {
    "ConsentId": "6a6a826f-0930-4eb0-b365-a8eac3032828",
    "CreationDateTime": "2024-06-27T15:27:13+0300",
    "Status": "Authorized",
    "StatusUpdateDateTime": "2024-06-27T16:27:13+0300",
    "Permissions": [
        "ReadInsurancePoliciesMotor"
    ],
    "ExpirationDateTime": "2024-03-28T15:27:13+030",
    "Purpose": [
        "MotorInsuranceQuote"
    ]
  },
  "Subscription": {
    "Webhook": {
      "Url": "https://api.tpp1.com/webhook/callbackUrl",
      "IsActive": false
    }
  },
  "Links": {
    "Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-draft3rc1/insurance-consents/6a6a826f-0930-4eb0-b365-a8eac3032828"
  },
  "Meta": {}
}

...

Code Block
GET /open-finance/insurance/v1.0-draft3rc1/insurance-policies HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/json
x-fapi-interaction-id: 9a371b79-4e79-4d7d-a77d-380c528ab8c0
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

...

Code Block
{
    "typ": "JWT",
    "alg": "PS256",
    "kid": "e4ce77c498e77000a25aa7b40e4a83f9"
}
.
{
    "iss": "s6BhdRkqt3",
    "iat": 1669393154,
    "exp": 1669393496,
    "nbf": 1669393154,
    "aud": "https://server.example.com",
    "response_type": "code",
    "redirect_uri": "https://openbanking.tpp1.ae/simple-redirect-url",
    "scope": "insurance",
    "state": "2616df22-899e-468b-b7af-927145b067cc",
    "authorization_details": [
        {
            "Type": "urn:openfinanceuae:insurance-consent:v1.0-draft3rc1",
            "Consent": {
                "ConsentId": "6a6a826f-0930-4eb0-b365-a8eac3032828",
                "Permissions": [
                    "ReadInsurancePoliciesMotor"
                ],
                "ExpirationDateTime": "2024-03-28T15:27:13+030",
                "Purpose": [
                    "MotorInsuranceQuote"
                ]
            },
            "Subscription": {
                "Webhook": {
                    "Url": "https://api.tpp1.com/webhook/callbackUrl",
                    "IsActive": false
                }
            }
        }
    ]
}

...

Code Block
PATCH /open-finance/insurance/v1.0-draft3rc1/insurance-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/json
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "Subscription": {
    "Webhook": {
      "IsActive": true
    }
  }
}

...

Code Block
PATCH /open-finance/insurance/v1.0-draft3rc1/insurance-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/json
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "Subscription": {
    "Webhook": {
      "IsActive": false
    }
  }
}

...

Code Block
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 1664950125,
  "nbf": 1664950125,
  "aud": [
    "6uC8HSQ8C59SDSw43Cdm9YWxxjJmDV"
  ],
  "iat": 1661378036,
  "message": {
    "Data": {
      "PolicyType": "Motor",
      "PolicyDetails": {
        "InsurancePolicyId": "176794ea-ee8c-4621-b824-b8cfa95db0ff",
        "CustomerId": "dcaaef9c-63cb-4c57-9f2a-a4986c4a958e",
        ...
      }
    },
    "Links": {
      "Self": "https://rs1.openfinanceplatform.ae/open-finance/insurance/v1.0-draft3rc1/insurance-policies/176794ea-ee8c-4621-b824-b8cfa95db0ff"
    },
    "EventMeta": {
      "EventDateTime": "2022-08-24T07:28:00.556Z",
      "EventResource": "insurance-policies",
      "EventType": "UAEOF.Resource.Updated",
      "ConsentId": "6a6a826f-0930-4eb0-b365-a8eac3032828"
    }
  }
}
.
<<signature>>

...

See the Insurance API - OpenAPI Documentation page.

6. Notes

  • Customer payment details require the ReadMotorInsuranceCustomerPaymentDetails permission and must be specifically requested using the get /insurance-policies/{InsurancePolicyId}/customer-payment-details operation. This is to ensure a separation of concerns between the main body of data and the payment details.

7. Security

A insurance scope is used for accessing the insurance endpoints.