Introduction
This guide describes the Property Insurance APIs available on Yasmina’s platform. These APIs cover the core operations required for property insurance. This includes getting prices, issuing and managing policies, generating payment links, and handling claims. Our APIs follow the RESTful standard and are structured to provide consistent inputs and outputs, making them straightforward to integrate, test, and maintain within your systems.What you will learn
- Getting prices for property insurance
- Issuing policies
- Uploading images for your insured property
- Starting a claim
Prerequisites
- Account in Yasmina - See the Onboarding section for details. You need to add “Property (Multiple Providers)” in the products field.
- Authenticated Token - Follow the Authentication guide to generate one.
- Backend server - Required to securely call Yasmina APIs.
Get prices
Yasmina works with multiple insurance providers. You can retrieve and compare prices using the List Prices API. This helps your customers choose their most suitable option. Currently, we are provide pricing from the following five providers:- Walaa
- Medgulf
- Tawuniya
- Takaful Al-Rajhi
- Wataniya
Issue policies
To issue policies, use the Issue Policies API. The following fields are required when creating a Property Insurance request. All requests must conform to these validation rules.| Field | Type | Rules | Description |
|---|---|---|---|
insurance_provider | string | required, in: walaa | This comes from the prices API |
personal_details | object | required | Contains personal information of the policyholder. |
personal_details.name | string | required, max:255 | Full name of the policyholder. |
personal_details.gender | string | required, in: M, F | Gender of the policyholder. |
personal_details.email | string | required, max:255 | Email address of the policyholder. |
personal_details.phone_number | string | required, regex: /^\+\d{10,15}$/ | Phone number in international format (e.g., +966512345678). |
personal_details.birthdate | date | required | Date of birth (ISO 8601 format recommended, e.g., 1990-05-20). |
personal_details.nationality | string | required, in: list of supported countries | Country code of nationality (must match supported country codes). |
personal_details.nationality_id | string | required, max:20 | National ID, Iqama, or passport number. |
building_details | object | required | Details of the insured building. |
building_details.building_age | integer | required, min:0 | Age of the building in years. |
building_details.building_type | string | required, in: apartment, villa, private_accommodation | Type of property. |
building_details.apartment_size | integer | required, min:0 | Size of apartment in square meters (if applicable). |
address | object | required | Full address of the property. |
address.street_name | string | required, max:255 | Street name of the property. |
address.building_number | string | required, max:50 | Building number. |
address.district_name | string | required, max:255 | District/area name. |
address.city_name | string | required, in: availableCities config | City name (must match Yasmina’s supported cities list). |
address.additional_number | string | required, max:20 | Additional number (Saudi address standard). |
address.zip_code | string | required, max:20 | Zip/postal code. |
address.unit_number | string | required, max:20 | Unit/flat number. |
property_cost | numeric | nullable, required_without: contents_cost | Estimated value of the building/property. Required if contents_cost is not provided. |
contents_cost | numeric | nullable, required_without: property_cost | Estimated value of the home contents. Required if property_cost is not provided. |
has_agreed_to_terms_and_conditions | boolean | accepted (true, 1, yes) | Must explicitly confirm acceptance of terms and conditions. |
Understanding Payment and Policy activation
When you first make a request to the Issue Policy API. The Policy is not yet activated and thestatus is 0 (which means pending).
Also the provider_policy and provider_policy_id will both be null.
In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the status becomes 1.
Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.
Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor.
Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor.
On Staging and Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test