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 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
- Issuing policies
- Uploading images for your insured property
- Starting a claim
Prerequisites
- Account in Yasmina - See the Onboarding section for details.
- Authenticated Token - Follow the Authentication guide to generate one.
- Backend server - Required to securely call Yasmina APIs.
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 |
|---|---|---|---|
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