Property Insurance

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 - You can follow the Authentication guide or head straight to the Generate Token API.
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

Address from Short Code

The GET Address Endpoint allows you to retrieve the full property address by providing only a short address code (e.g., Saudi Post short code). It is especially useful when users enter or scan their short address, and you need to automatically fill in the property details in the form. Example of a request

GET /api/v1/property/address-from-short?short_address=RRRC7866 HTTP/1.1
Host: portal.yasmina.ai
Authorization: Bearer <token>
Accept: application/json

Example of a response

{
    "building_number": "7866",
    "zip_code": "13342",
    "additional_number": "2641",
    "street_name": "Ahmad Al Gazali",
    "district_name": "Al Arid Dist.",
    "city_name": "Riyadh"
}

Please note that the short address API does not provide unit_number. This needs to be supplied separately to the Issue Policy API

Policies

Issue a policy

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.

Example request:

POST /api/v1/property/policies HTTP/1.1
Host: localhost:8000
Accept: application/json
Content-Type: application/json
Authorization: ••••••
Content-Length: 868

{
    "insurance_provider": "walaa",
    "personal_details": {
        "email": "[email protected]",
        "gender": "M",
        "name": "Customer Name",
        "phone_number": "+9665XXXXXXX",
        "birthdate": "1990-01-01",
        "nationality": "JO",
        "nationality_id": "**********"
    },
    "building_details": {
        "building_age": 20,
        "building_type": "villa",
        "apartment_size": 200
    },
    "address": {
        "street_name": "Street Name",
        "district_name": "District Name",
        "city_name": "Riyadh",
        "additional_number": "X",
        "zip_code": "XXXXX",
        "unit_number": "X",
        "building_number": "X"
    },
    "property_cost": 500000,
    "content_cost": 100000,
    "has_agreed_to_terms_and_conditions": true,
    "redirect_url": "https://www.example.com?policy_id=XXXXXX"
}

Example Response

{
    "id": 874,
    "meta_data": {
        "address": {
            "zip_code": "11193",
            "city_name": "Riyadh",
            "street_name": "Street Name",
            "unit_number": "X",
            "district_name": "District Name",
            "building_number": "X",
            "additional_number": "X"
        },
        "property_cost": 500000,
        "building_details": {
            "building_age": 20,
            "building_type": "villa",
            "apartment_size": 200
        },
        "personal_details": {
            "name": "Customer Name",
            "email": "[email protected]",
            "gender": "M",
            "birthdate": "1990-01-01",
            "nationality": "JO",
            "phone_number": "+96279XXXXXXX",
            "nationality_id": "**********"
        },
        "insurance_provider": "walaa",
        "has_agreed_to_terms_and_conditions": true
    },
    "created_at": "2025-11-20T12:06:09.000000Z",
    "canceled_at": null,
    "status": 0,
    "provider_policy": null,
    "provider_policy_id": null,
    "client_id": "********-****-****-****-************",
    "payment_link": "http://localhost:8000/short/XXXXX",
    "price": 603.75,
    "redirect_url": "https://www.google.com?policy_id=874",
    "policy_url": null
}

Retrieving the policy object again

You can retrieve the policy objects that were created by you any time by either using the Listing policies API or the Show policy API The Listing policy API can take some filters to retrieve only specific policies. This might be helpful if you have your own internal system and want to list policies by different values. Example Request

GET /api/v1/property/policies?nationality_id=9881052027 HTTP/1.1
Accept: application/json
Authorization: ••••••

The Show Policy API will retrieves a specific policy object based on path ID Example Request

GET /api/v1/property/policies/875 HTTP/1.1
Accept: application/json
Authorization: ••••••

Cancellation Status

The Cancellation Status API provides real-time visibility into the cancellation state of a policy. Upon receiving a request, Yasmina initiates a query to the relevant insurance provider, fetches the current policy information, and returns a structured response reflecting the latest cancellation status. This ensures your system always displays accurate and timely policy data. Example Request

GET /api/v1/property/policies/849/cancellation-status HTTP/1.1
Accept: application/json
Authorization: ••••••

Example Response

{
    "status": "active"
}

Payment and Policy activation

When you first make a request to the Issue Policy API. The Policy is not yet activated and the status 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.

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

Redirect URL

You can supply the payload a redirect_url. This is used to redirect the customer to any page or deep link you need. You can also include a query string with policyID and it will automatically replace it with the actual id of the policy object. Example for policy id 123

	{
		...,
		redirect_url: "https://www.example.com?yasmina_policy_id=policyID"
	}

Will become on the response

	{
		...,
		redirect_url: "https://www.example.com?yasmina_policy_id=123"
	}

And the customer that purchased the policy will be redirected to https://www.example.com?yasmina_policy_id=123

Upload Images

Supporting documents are required from your clients. These can include home photos, images of valuable contents, or surrounding areas. You can upload these documents using the Upload Document API

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

Introduction

What you will learn

Prerequisites

Get prices

Address from Short Code

Policies

Issue a policy

Retrieving the policy object again

Cancellation Status

Payment and Policy activation

Redirect URL

Upload Images

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

​Introduction

​What you will learn

​Prerequisites

​Get prices

​Address from Short Code

​Policies

​Issue a policy

​Retrieving the policy object again

​Cancellation Status

​Payment and Policy activation

​Redirect URL

​Upload Images

Introduction

What you will learn

Prerequisites

Get prices

Address from Short Code

Policies

Issue a policy

Retrieving the policy object again

Cancellation Status

Payment and Policy activation

Redirect URL

Upload Images