> ## Documentation Index > Fetch the complete documentation index at: https://docs.yasmina.ai/llms.txt > Use this file to discover all available pages before exploring further. # Motor Insurance > Seamless insurance for the cars you're selling and the drivers that are buying from you.

Build it with AI — an AI coding assistant can scaffold this entire integration for you straight from these docs. See Build with AI to get started.

## Introduction This guide describes the Yasmina's **Motor Insurance APIs for Single Insurance Provider**, covering both comprehensive and TPL cover (for Multiple Insurance Providers with Price comparison, [click here](/price-comparison/motor-insurance)) available on Yasmina’s platform. These APIs cover the core operations required for working with 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 * Uploading vehicle photos * Issuing and managing policies * Payment link * Starting a claim ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need to add "Comprehensive Motor Insurance (Single Provider)", "TPL Motor Insurance (Single Provider)", or both in the products field, depending on the cover you offer. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Vehicle photos If the customer has selected a comprehensive policy, upload the five photos before you issue the policy — front, back, right, left, and the chassis (VIN) number. Use the Upload Vehicle Photos API, against the quote request and the price the customer selected. This step is required for comprehensive cover. If the photos are not uploaded, the customer cannot continue with the purchase. It must happen before you request the payment OTP. Example of a request ``` POST /api/v1/car-comp/quote-requests/11/attachments HTTP/1.1 Authorization: Bearer ***** Content-Type: multipart/form-data quote_price_id=e059d28e-a519-43af-b9d4-e1cc5d97ecb7 front=@front.jpg back=@back.jpg right=@right.jpg left=@left.jpg chassis=@chassis.jpg ``` * **All five together.** A partial upload is rejected with a `422`. * **JPG or PNG, up to 3 MB each.** * **Once per vehicle.** The insurance provider keeps the first set it accepts. A later upload for the same vehicle still succeeds, with `already_registered: true` in the response, but the registered photos do not change — so check the photos before sending them. * **Comprehensive only.** A `quote_price_id` belonging to a TPL quote is rejected. ## 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 | | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `otp` | `123456` | The OTP received by the customer. Required for issuing a comprehensive policy. | | `owner_id` | `2234567890` | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | 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. For a Saudi national ID (starts with `1`) give a Hijri date; for an Iqama ID (starts with `2`) give a Gregorian date. | | `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). Use this OR `custom_number` — one is required. | | `custom_number` | `1234567890` | Custom car number for newly imported cars. Use this OR `car_sequence_number`. | | `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 (starts with `1`) or Iqama ID (starts with `2`). **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. | The customer's Saudi IBAN is collected earlier in the flow: it is a required field of the Issue OTP API, not of this endpoint. Example of a comprehensive request ``` POST /api/v1/car-comp/policies HTTP/1.1 Authorization: Bearer ***** Content-Type: application/json Accept: application/json Content-Length: 212 { "otp": "123456", "owner_id": 2234567890, "email": "someone@example.com", "phone": "05XXXXXXXX", "birthdate": "1982-04-20", "custom_number": "1234567890", "is_ownership_transfer": false, "car_estimated_cost": 45000, "car_model_year": 2024 } ``` Example of a TPL 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": "someone@example.com", "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": "1001364939", "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 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.