TPL Motor Insurance

Introduction

This guide describes Yasmina’s TPL Motor Insurance APIs available on Yasmina’s platform (for Multiple Insurance Providers with Price comparison, click here). These APIs cover the core operations required for working with TPL motor insurance, including 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

Issuing and managing policies
Payment link
Starting a claim

Prerequisites

Account in Yasmina - See the Onboarding section for details. You need to add “TPL Motor Insurance (Single Provider)” in the products field.
Authenticated Token - Follow the Authentication guide to generate one.
Backend server - Required to securely call Yasmina APIs.

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 policy

In order to Issue a policy. You can head to the Issue Policy API These are the fields that you need to provide:

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).
`birthdate`	`1988-04-20`	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`	Saudi mobile number. Must start with `05` and be exactly 10 digits.
`car_sequence_number`	`52423810`	The car’s sequence number (8–9 digits).
`is_ownership_transfer`	`false`	Boolean flag. `true` if the car is being transferred to a new owner, otherwise `false`.
`current_car_owner_id`	`1234567890`	The current owner’s national ID. Only required if `is_ownership_transfer = true`.
`car_estimated_cost`	`45000`	Estimated market cost of the car in SAR.
`car_model_year`	`2026`	Year of manufacture of the car. Must be between 1950 and the next year.

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

{
    "owner_id": 2234567890,
    "email": "[email protected]",
    "phone": "05XXXXXXXX",
    "birthdate": "1982-04-20",
    "car_sequence_number": 52423810,
    "is_ownership_transfer": false,
    "car_estimated_cost": 45000,
    "car_model_year": 2024
}

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

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

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.

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.

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

Introduction

What you will learn

Prerequisites

Prerequisites

Issue policy

Understanding Payment and Policy activation

Showing a policy

Listing policies

Claims

​Introduction

​What you will learn

​Prerequisites

​Prerequisites

​Issue policy

​Understanding Payment and Policy activation

​Showing a policy

​Listing policies

​Claims

Introduction

What you will learn

Prerequisites

Prerequisites

Issue policy

Understanding Payment and Policy activation

Showing a policy

Listing policies

Claims