Comprehensive Motor Insurance

Introduction

This guide introduces Yasmina’s Comprehensive Motor Insurance APIs for Multiple Insurance Providers (for the single-provider version, click here). These APIs enable you to retrieve quotes from several insurance companies before issuing a policy to your customer. The guide covers all key operations, including requesting quotes, issuing and managing policies, generating payment links, and handling claims. Our APIs are built on RESTful principles and follow consistent input and output structures, making them simple to integrate, test, and maintain within your systems

What you will learn

Request OTPs
Requesting and managing quotes
Issuing and managing policies

Prerequisites

Account in Yasmina - See the Onboarding section for details. You need to add “Comprehensive Motor Insurance (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.

Quotes

Quotes represent the different premiums, benefits, and deductibles offered by insurance providers. Before issuing a Comprehensive Motor Insurance policy, you need to provide the car details to retrieve quotes from various insurance providers. These quotes are then used when issuing the policy.

OTP for quotations

Before requesting quotations, we need to verify the Phone number of the customer through an OTP. You can do that using the Quote OTP API You need to provide the following properties for the Quote OTP API:

Field	Example Value	Description
`owner_id`	`2234567890`	The owner’s national ID. Must be 10 digits and typically starts with 1, 2, or 7.
`email`	`[email protected]`	The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers).
`phone`	`05XXXXXXXX`	Saudi mobile number. Must start with `05` and be exactly 10 digits.

Example Payload

POST /api/v1/car-comp/quote-otp HTTP/1.1
Host: sandbox.yasmina.ai
Accept: application/json
Authorization: Bearer token
Content-Type: application/json
Content-Length: 93

{
    "email": "[email protected]",
    "phone": "0512345678",
    "owner_id": "1234567890"
}

The customer should then get an OTP. The API itself will simply return 204 No Content. Afterwards you will be ready to Request Quotations.

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 logo, 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 2 minutes before making the request.

You need to provider the following properties for the Request Quotes API:

Field	Example Value	Is Required	Description
`otp`	`123456`	Yes	The OTP received by the customer from the Request OTP API.
`owner_id`	`2234567890`	Yes	The owner’s national ID. Must be 10 digits and typically starts with 1, 2, or 7.
`email`	`[email protected]`	Yes	The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers).
`birthdate`	`1988-04-20`	Yes	Date 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.
`phone`	`05XXXXXXXX`	Yes	Saudi mobile number. Must start with `05` and be exactly 10 digits.
`car_sequence_number`	`52423810`	Yes	The car’s sequence number (8–9 digits). Use this OR `custom_number` — one is required.
`custom_number`	`1234567890`	Yes	Custom car number for newly imported cars. Use this OR `car_sequence_number` — one is required.
`is_ownership_transfer`	`false`	No	Boolean flag. `true` if the car is being transferred to a new owner, otherwise `false`. Defaults to `false` when omitted.
`current_car_owner_id`	`1234567890`	Yes (if transfer)	The current owner’s national ID. Only required if `is_ownership_transfer = true`.
`car_estimated_cost`	`45000`	Yes	Estimated market cost of the car in SAR.
`car_model_year`	`2026`	Yes	Year of manufacture of the car. Must be between 1950 and the next year.
`start_date`	`2025-12-01`	No	Start date of the policy (format: `YYYY-MM-DD`). Must be between the next day and 28 days from today (inclusive). Yasmina validates this range server-side.
`drivers`	See below	No	An array of driver objects. When provided, the sum of all `driving_percentage` values must equal 100, and the owner must be included among the drivers.

Drivers Array

When providing drivers, each driver object must include the following fields:

Field	Example Value	Is Required	Description
`owner_id`	`2234567890`	Yes	Driver’s national ID. Must be 10 digits and starts with 1, 2, or 7.
`birthdate`	`1988-04-20`	Yes	Driver’s date of birth in `YYYY-MM-DD` format.
`driving_percentage`	`50`	Yes	Percentage of driving for this driver. Valid values: `25`, `50`, `75`, or `100`. The sum of all drivers’ percentages must equal 100.

When drivers are provided, the vehicle owner must be included among the drivers.

Example request

POST /api/v1/car-comp/quote-requests HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: ••••••
Content-Length: 226

{
    "otp": "123456",
    "owner_id": 2234567890,
    "email": "[email protected]",
    "phone": "05XXXXXXXX",
    "birthdate": "1982-04-20",
    "custom_number": "1234567890",
    "is_ownership_transfer": false,
    "car_estimated_cost": 45000,
    "car_model_year": 2024,
    "drivers": [
        {
            "owner_id": "2234567890",
            "birthdate": "1982-04-20",
            "driving_percentage": 50
        },
        {
            "owner_id": "1234567891",
            "birthdate": "1990-06-15",
            "driving_percentage": 50
        }
    ]
}

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": 1234567890,
  "email": "[email protected]",
  "phone": "0555555555",
  "birthdate": "1990-01-01",
  "car_sequence_number": 1111111111,
  "is_ownership_transfer": true,
  "current_car_owner_id": "7000000000",
  "car_estimated_cost": 45000,
  "car_model_year": 2024,
  "drivers": [
    {
      "owner_id": "1234567890",
      "birthdate": "1990-01-01",
      "driving_percentage": 50
    },
    {
      "owner_id": "2345678901",
      "birthdate": "1985-06-20",
      "driving_percentage": 50
    }
  ],
  "quotes": [
    {
      "type": "Comprehensive",
      "fix_type": "workshop",
      "vehicle_estimated_value": 45000,
      "company_logo": "https://axjqy4nuifd8.compat.objectstorage.me-jeddah-1.oraclecloud.com/Yasmina-Dev-bucket/logos/takaful.png",
      "company_logo_url": "https://axjqy4nuifd8.compat.objectstorage.me-jeddah-1.oraclecloud.com/Yasmina-Dev-bucket/company-logos/art.png",
      "square_company_logo_url": "https://axjqy4nuifd8.compat.objectstorage.me-jeddah-1.oraclecloud.com/Yasmina-Dev-bucket/insurance-logos/alrajhi.png",
      "company_name": "Al Rajhi Takaful",
      "company_name_ar": "تكافل الراجحي",
      "type": "Comprehensive",
      "insurance_type_display": "Comprehensive",
      "insurance_type_display_ar": "شامل",
      "quote_reference_id": "6c7c18a7-ee89-49fe-9f7e-dde72ad809ce",
      "prices": [
        {
          "quote_price_id": "f5d52340-3661-48af-b81a-028f251ef6a9",
          "deductible": 500,
          "subtotal": 5232.12,
          "vat_percentage": 15,
          "vat": 784.82,
          "total": 6016.94
        }, ...
      ],
      "benefits": [
        {
          "quote_benefit_id": "f72846cb-98ed-4b78-b3b5-bb0d587f8da5",
          "id": "1296",
          "name": "Natural Disasters",
          "name_ar": "كوارث طبيعية",
          "amount": 0,
          "vat": 0,
          "url": null
        }, ...
      ]
    }
  ],
  "client_id": "9f757acd-1ab4-466f-8cb2-d65ddedb2374",
  "updated_at": "2025-10-06T22:03:56.000000Z",
  "created_at": "2025-10-06T22:03:56.000000Z",
  "id": 25
}

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.

Arabic localisation fields

Each quote object includes Arabic counterparts for the fields that typically appear in the UI. Use these when rendering an Arabic experience:

Field	Arabic equivalent	Notes
`company_name`	`company_name_ar`	Arabic name of the insurance company
`insurance_type_display`	`insurance_type_display_ar`	Arabic label for the insurance type as the provider intends it to be shown. Falls back to the English value for provider-specific types without a translation
`benefits[].name`	`benefits[].name_ar`	Arabic name of each benefit

insurance_type and type are normalised category values used internally for filtering (TPL, TPL +, Comprehensive) and do not have Arabic equivalents — use insurance_type_display_ar for display purposes.

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.

Issuing policies

Issue Policy OTP

When a customer selects a quotation, they need to go through another OTP check. This time you need to request it through the Issue OTP API The Issue Policy OTP requires the following fields:

Field	Example Value	Description
`quote_request_id`	Yasmina’s unique identifier for the quote request. This must match the `id` returned when creating a quote request.
`quote_reference_id`	The unique reference ID provided by the insurance company. Required when issuing a policy.
`quote_price_id`	The selected price option ID. Each quote has multiple prices with different deductibles.
`owner_id`	`2234567890`	The owner’s national ID. Must be 10 digits and typically starts with 1, 2, or 7.
`email`	`[email protected]`	The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers).
`phone`	`05XXXXXXXX`	Saudi mobile number. Must start with `05` and be exactly 10 digits.

Example request:

POST /api/v1/car-comp/issue-otp HTTP/1.1
Host: sandbox.yasmina.ai
Accept: application/json
Authorization: Bearer token
Content-Type: application/json
Content-Length: 249

{
    "email": "[email protected]",
    "phone": "0512345678",
    "owner_id": "2234567890",
    "quote_request_id": 62,
    "quote_reference_id": "feb9e0ec-d71c-4c60-99d4-22ad9a5c97ec",
    "quote_price_id": "f0a13788-92c3-f011-972d-005056a9891a"
}

Similar to the request OTP API. The customer will receive another OTP and the API will return 204 - No Content on success. The OTP must be supplied to the Issue Policy API

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

Field	Description
`quote_request_id`	Yasmina’s unique identifier for the quote request. This must match the `id` returned when creating a quote request.
`quote_reference_id`	The unique reference ID provided by the insurance company. Required when issuing a policy.
`quote_price_id`	The selected price option ID. Each quote has multiple prices with different deductibles.
`benefits`	A list of selected benefit IDs. Only required if the benefit has a cost (`amount > 0`).
`extra_data`	Optional 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
`redirect_url`	Optional URL that the customer gets redirected to once a successful purchase is made
`otp`	The OTP that you got from the issue-otp API

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

{
  "otp": "123456",
  "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
  }
}

Once you make a request to the Issue Policy API, you will get the Policy object with a 201 HTTP response code. Here is an example of the Policy object.

{
    "id": 700,
    "meta_data": {
        "extra_data": null,
        "new_owner_id": "2528297837",
        "quote_price_id": "f5d52340-3661-48af-b81a-028f251ef6a9",
        "quote_request_id": 25,
        "previous_owner_id": "7001364939",
        "car_sequence_number": 723787810
    },
    "provider_policy_id": null,
    "provider_policy": null,
    "created_at": "2025-10-06T23:31:17.000000Z",
    "status": 0,
    "payment_link": "http://localhost:8000/short/wVln4",
    "price": 6016
}

This is a summary of the fields returned in the policy object

Field	Description
`id`	Yasmina’s unique identifier for the policy.
`meta_data`	A JSON object that contains information about the fields that were used to generate this policy. `extra_data` will also be returned here.
`provider_policy_id`	The policy ID that is returned by the policy provider.
`provider_policy`	A URL that contains the policy in PDF format.
`created_at`	When was the policy issued.
`status`	0 = Pending, 1 = Issued.
`payment_link	A secure payment link generated by Yasmina
`price`	The price of the policy in Saudi Riyal

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

Showing a policy

In order to get a status of a policy, you can use the Show Policy API. This API, takes a Yasmina Policy id and will return the policy object This API is ideal when you want to re-fetch a specific policy after the PDF gets generated. Example of a request

GET /api/v1/car-comp/policies/123 HTTP/1.1
Host: production.yasmina.ai
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Example a response

{
    "id": 659,
    "meta_data": {
        "extra_data": {
        },
        "new_owner_id": "2467701575",
        "quote_price_id": "097116f9-99b1-491f-a2ab-f86b2c535cbe",
        "quote_request_id": 4,
        "previous_owner_id": "2467701575",
        "car_sequence_number": 52423810
    },
    "product_id": 4,
    "provider_policy_id": "53018c24-b246-4bef-866f-4a54c2367196",
    "provider_policy": "policy.pdf",
    "created_at": "2025-09-07T07:53:55.000000Z",
    "status": 1,
    "payment_link": null,
    "price": null
}

Listing policies

You can also use the List Policies API to get a list of all policies that were generated from our system. You might use this on your admin interface, or if you just want to check what has been generated.

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

Introduction

What you will learn

Prerequisites

Quotes

OTP for quotations

Request Quotes

Drivers Array

Explaining the Quotes Request response

Arabic localisation fields

List Quotes Requests

Delete Quotes Requests

Issuing policies

Issue Policy OTP

Issuing a policy

Payment and Policy activation

Redirect URL

Showing a policy

Listing policies

​Introduction

​What you will learn

​Prerequisites

​Quotes

​OTP for quotations

​Request Quotes

​Drivers Array

​Explaining the Quotes Request response

​Arabic localisation fields

​List Quotes Requests

​Delete Quotes Requests

​Issuing policies

​Issue Policy OTP

​Issuing a policy

​Payment and Policy activation

​Redirect URL

​Showing a policy

​Listing policies

Introduction

What you will learn

Prerequisites

Quotes

OTP for quotations

Request Quotes

Drivers Array

Explaining the Quotes Request response

Arabic localisation fields

List Quotes Requests

Delete Quotes Requests

Issuing policies

Issue Policy OTP

Issuing a policy

Payment and Policy activation

Redirect URL

Showing a policy

Listing policies