​
Introduction

This guide describes the Motor Insurance APIs available on Yasmina’s platform. These APIs cover the core operations required for working with TPL motor insurance, including requesting quotes, issuing and managing policies, generating payment link, and handling claims. Our APIs use the RESTful standard and is structured to provide consistent inputs and outputs, making it quick and easy to integrate, test, and maintain within your systems.

​
What you will learn

  • Requesting and managing quotes
  • Issuing and managing policies
  • Starting a claim

​
Prerequisites

  1. Account in Yasmina - See the Onboarding section for details.
  2. Authenticated Token - Follow the Authentication guide to generate one.
  3. Backend server - Required to securely call Yasmina APIs.

​
Quotes

Quotes are the different premiums, benefits, and deductibles offered by insurance providers. Before issuing a TPL Motor insurance policies you need to give the car details to get different quotes from insurance providers. These quotes are then used to issuing the policy.

​
Request Quotes

In order to provide quotes for your customer you need to execute the Request Quotes API. This API provides an array response from different insurance providers. Each item in this array, represents the name of the company, the different premiums and deductibles, and also the list of benefits (both free and paid).
The Request Quotes API may take longer to respond because it retrieves results from multiple insurance providers. Be sure to increase your timeout to at least 1 minute before making the request.
You need to provider the following properties for the Request Quotes API
FieldExample ValueDescription
owner_id2234567890The owner’s national ID. Must be 10 digits and typically starts with 1, 2, or 7.
birthdate1988-04-20Date of birth of the owner in YYYY-MM-DD format. If the owner ID is a Saudi National, then you need to give Hijri date, otherwise you need to give a Gregorian birthdate.
phone05XXXXXXXXSaudi mobile number. Must start with 05 and be exactly 10 digits.
car_sequence_number52423810The car’s sequence number (8–9 digits).
is_ownership_transferfalseBoolean flag. true if the car is being transferred to a new owner, otherwise false.
current_car_owner_id1234567890The current owner’s national ID. Only required if is_ownership_transfer = true.
car_estimated_cost45000Estimated market cost of the car in SAR.
car_model_year2026Year of manufacture of the car. Must be between 1950 and the next year.
Example request 
POST /api/v1/car-comp/quote-requests HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: ••••••
Content-Length: 226

{
    "owner_id": 2234567890,
    "phone": "05XXXXXXXX",
    "birthdate": "1982-04-20",
    "car_sequence_number": 52423810,
    "is_ownership_transfer": false,
    "car_estimated_cost": 45000,
    "car_model_year": 2024
}
Once you execute this you will get a response that includes pricing and benefits from multiple insurance providers. This is an example of a response in json 
{
    "owner_id": 2234567890,
    "phone": "05XXXXXXXX",
    "birthdate": "1982-04-20",
    "car_sequence_number": 52423810,
    "is_ownership_transfer": false,
    "car_estimated_cost": 45000,
    "car_model_year": 2025,
    "quotes": [
        {
            "company_name": "Al Rajhi Takaful",
            "quote_reference_id": "da94ea3b-73d3-4b76-a831-e880d56397e4",
            "prices": [
                {
                    "quote_price_id": "85ebb1d6-3867-4f4f-ab37-afec22994f4e",
                    "deductible": 500,
                    "subtotal": 2979.23,
                    "vat_percentage": 15,
                    "vat": 446.88,
                    "total": 3426.11
                },
                {
                    "quote_price_id": "d44485c7-e725-4e3f-9377-31341265375d",
                    "deductible": 1000,
                    "subtotal": 2934.95,
                    "vat_percentage": 15,
                    "vat": 440.24,
                    "total": 3375.19
                },
                ...
            ],
            "benefits": [
                {
                    "quote_benefit_id": "ee387127-4521-403d-b7a0-92e38fbe3d78",
                    "id": "1296",
                    "name": "Natural Disasters",
                    "amount": 0,
                    "vat": 0,
                    "url": null
                },
                {
                    "quote_benefit_id": "faa941bf-a9dd-4a10-a4eb-51bd5d1e7884",
                    "id": "601061",
                    "name": "Replacement Car",
                    "amount": 325,
                    "vat": 48.75,
                    "url": null
                },
                ...
            ]
        },
        {
            "company_name": "United Cooperative Assurance",
            "quote_reference_id": "fc5533cb-dd52-4885-a7ce-4d81ff8f674f",
            "prices": [
                {
                    "quote_price_id": "f547a59b-d197-4eca-8367-0c3dd8550810",
                    "deductible": 2000,
                    "subtotal": 2420,
                    "vat_percentage": 15,
                    "vat": 363,
                    "total": 2783
                },
                ...
            ],
            "benefits": [
                {
                    "quote_benefit_id": "790623f6-ab25-4deb-94bf-49f4a2de2977",
                    "id": "1757225845262350",
                    "name": "Personal Accident (Drive only cover)",
                    "amount": 40,
                    "vat": 6,
                    "url": null
                },
                ...
            ]
        }
    ],
    "current_car_owner_id": 2234567890,
    "client_id": "9f757acd-1ab4-466f-8cb2-d65ddedb2374",
    "updated_at": "2025-09-07T06:17:28.000000Z",
    "created_at": "2025-09-07T06:17:28.000000Z",
    "id": 9
}

​
Explaining the Quotes Request response

The ID value represents Yasmina’s unique identifier for this quote request. You will later need to provide in the Issue policy API as quote_id The Quote reference ID must also be provided to the Issue Policy API as quote_reference_id. Each insurance provider has its own quote_reference_id. Each insurance provider gives a prices array. This represents different pricing options. Each has its own deductible and total. You will need to provide quote_price_id when issuing a policy. Finally we have the benefits array. We have two types. Some require an additional price and are optional (amount > 0), while others are considered free and are automatically added (amount = 0). For those that have a price, you need to provide the quote_benefit_id in the benefits array in the Issue Policy API.

​
List Quotes Requests

You can list a paginated list of all the quote requests that your account has generated. In order to do so, you can use the List quote requests API You can filter these by using owner_id in the query string. This may be useful in case your customer navigated from one page to another and you need to show the quote requests again (rather than making a new request) Example: GET /car-api-reference/quotes/list-quotes?page=2&per_page=1&owner_id=1234567890

​
Delete Quotes Requests

You can delete some of the requests from the system using the Delete Quotes Requests API. This is rarely used, but may be helpful if you’d like to reduce the items listed.

​
Issue policy

In order to Issue a policy. You can head to the Issue Policy API You need to use the fields that were retrieved in the Request Quotes API.
FieldDescription
quote_request_idYasmina’s unique identifier for the quote request. This must match the id returned when creating a quote request.
quote_reference_idThe unique reference ID provided by the insurance company. Required when issuing a policy.
quote_price_idThe selected price option ID. Each quote has multiple prices with different deductibles.
benefitsA list of selected benefit IDs. Only required if the benefit has a cost (amount > 0).
extra_dataOptional JSON object to store additional metadata or custom values that can later be used in webhooks. Please keep minimal as it can’t exceed 255 characters
Example of a request 
POST /api/v1/car-comp/policies HTTP/1.1
Authorization: Bearer *****
Content-Type: application/json
Accept: application/json
Content-Length: 212

{
  "quote_request_id": 11,
  "quote_reference_id": "04486448-3433-43ef-a755-b07799d6580f",
  "quote_price_id": "e059d28e-a519-43af-b9d4-e1cc5d97ecb7",
  "benefits": [],
  "extra_data": {
      "extra_field": 1
  }
}
This is an example of the JSON payload that you might send. 
{
  "quote_request_id": 4,
  "quote_reference_id": "63c700d9-fd30-42a1-b914-5da099dafbbb",
  "quote_price_id": "097116f9-99b1-491f-a2ab-f86b2c535cbe",
  "benefits": [
      "71be7e33-f1fb-4f95-898d-9d6cbe7794d1"
  ],
  "extra_data": {
      "custom_field": 123
  }
}
To issue policies, you need to execute the Issue policies API

​
Claims

You can issue a claim using our APIs. When you issue a claim, we communicate it with the Insurance provider, and giving them details of the incident. Go to the Issue Claim API in order to start the claim process for your customer.