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 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.

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 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.

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 gets you an updated status of your policy. Yasmina makes a call to the insurance provider to inquire about the policy, and will return a response with updated status. Example Request

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

Example Response

{
    "status": "active"
}

Understanding 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

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

Address from Short Code

Policies

Issue policies

Retrieving the policy object again

Cancellation Status

Understanding Payment and Policy activation

Upload Images

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

​Introduction

​What you will learn

​Prerequisites

​Address from Short Code

​Policies

​Issue policies

​Retrieving the policy object again

​Cancellation Status

​Understanding Payment and Policy activation

​Upload Images

Introduction

What you will learn

Prerequisites

Address from Short Code

Policies

Issue policies

Retrieving the policy object again

Cancellation Status

Understanding Payment and Policy activation

Upload Images