> ## 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. # Comprehensive 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 introduces Yasmina’s **Comprehensive Motor Insurance APIs for Multiple Insurance Providers** (for the single-provider version, [click here](/single-provider-integrations/car)). 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 * Best practices and branding guidelines * Uploading vehicle photos * Issuing and managing policies ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need to add "Comprehensive Motor Insurance (Multiple Providers)" in the products field. 2. **Authenticated Token** - You can follow the Authentication guide or head straight to the Generate Token API. 3. **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 (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). | | `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": "someone@example.com", "phone": "0512345678", "owner_id": "1234567890" } ``` The customer should then receive an OTP. The API returns `204 No Content`. This quote OTP remains valid for 8 hours and can be reused for multiple quote requests during that period. You do not need to request a new quote OTP before every quotation. The response includes: * `X-OTP-Expires-In`: Remaining validity in seconds * `X-OTP-Expires-At`: Exact expiry time in ISO 8601 format Requesting a new quote OTP invalidates the previously issued quote OTP. After 8 hours, request a new OTP before submitting another quote request. 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` | `1234` | Yes | The four-digit OTP received by the customer from the Request OTP API. | | `owner_id` | `2234567890` | Yes | 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` | 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. 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` | Yes | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `car_sequence_number` | `52423810` | Conditional | The car’s sequence number (8-9 digits). Required when `custom_number` is not provided. Do not send both vehicle identifiers. | | `custom_number` | `1234567890` | Conditional | Customs card number for an imported vehicle (6-10 digits). Required when `car_sequence_number` is not provided. Also requires `maker_code`, `model_code`, and `body_type_code`. | | `maker_code` | `101` | With customs card | Vehicle maker code returned by the Vehicle Makers API. | | `model_code` | `1001` | With customs card | Vehicle model code returned by the Vehicle Models API for the selected `maker_code`. | | `body_type_code` | `3` | With customs card | Vehicle body-type code returned by the Vehicle Body Types API. | | `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 (starts with `1`) or Iqama ID (starts with `2`). **Only required if** `is_ownership_transfer = true`. | | `car_estimated_cost` | `45000` | Yes | Estimated market cost of the car in SAR. | | `car_model_year` | `2026` | No | Year of manufacture of the car. Must be between 1950 and the next year. If omitted, Yasmina uses the current year. | | `start_date` | `2026-07-28` | No | Start date of the policy in `YYYY-MM-DD` format. It must be after today and before the date 28 days from today. | | `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. | ### Customs card vehicle lookup If your customer identifies vehicles only by customs card number, collect the provider-compatible maker, model, and body-type codes before requesting a quote. Do not send codes from your own vehicle catalogue. All three lookup endpoints support an optional `q` query parameter. It searches English and Arabic names without case sensitivity. A complete numeric value searches by exact code. The maximum search length is 100 characters. #### 1. Search vehicle makers ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-makers?q=Toyota' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` Only makers with at least one available model are returned. #### 2. Search models for the selected maker `maker_code` is required. The returned model codes belong only to that maker. ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-models?maker_code=101&q=Corolla' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` #### 3. Search vehicle body types ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-body-types?q=SUV' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` Each lookup endpoint returns an array with the same structure: ```json theme={null} [ { "code": 101, "name_en": "Toyota", "name_ar": "تويوتا" } ] ``` For a customs card quote, send `custom_number`, `maker_code`, `model_code`, and `body_type_code`. Omit `car_sequence_number`. Yasmina registers the imported vehicle with the insurance platform before requesting quotations. If the vehicle is already registered, the quotation continues normally. #### 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 (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `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": "1234", "owner_id": "2234567890", "email": "someone@example.com", "phone": "05XXXXXXXX", "birthdate": "1982-04-20", "custom_number": "1234567890", "maker_code": 101, "model_code": 1001, "body_type_code": 3, "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": "someone@example.com", "phone": "0555555555", "birthdate": "1990-01-01", "car_sequence_number": 1111111111, "is_ownership_transfer": true, "current_car_owner_id": "1000000000", "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. ## Best practices and branding guidelines Show a provider attribution alongside every set of quotes — naming the licensed insurance broker behind the offers and its Insurance Authority licence — together with the support routes a customer can use if they need help. This is expected of every integration. Rather than hard-coding the wording, fetch it from the Guideline Texts API. English and Arabic come back together, so a bilingual page needs one request — and when the wording changes, it reaches you without an integration change. ``` GET /api/v1/car-comp/guideline-texts HTTP/1.1 Authorization: Bearer ***** Accept: application/json ``` The response has three parts under each locale: | Key | What it is | | ---------- | ---------------------------------------------------------------------------- | | `provider` | The attribution line — `pre`, `brand`, `brand_url`, `supervision`, `license` | | `support` | WhatsApp, terms and toll-free routes to the provider's support team | | `faq` | Eight question-and-answer pairs covering the questions buyers ask most | Rendered, the attribution reads *"Quotes are provided through **Shahin** · Under supervision of the Insurance Authority, license و س ط/No. 20158/82"*, with `brand` linking to `brand_url`. The FAQ is optional but recommended — it answers the questions buyers raise most often before choosing a policy. The licence number and the toll-free number are the same in both locales. Wrap them in `` so they are not reordered when the page is rendered right-to-left. ## 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. See Best practices and branding guidelines for what to show alongside the quotes. 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 ``` Example of a response ``` { "attachments": { "front": "https://cdn.yasmina.ai/vehicle-photos/abc123.jpg", "back": "https://cdn.yasmina.ai/vehicle-photos/def456.jpg", "right": "https://cdn.yasmina.ai/vehicle-photos/ghi789.jpg", "left": "https://cdn.yasmina.ai/vehicle-photos/jkl012.jpg", "chassis": "https://cdn.yasmina.ai/vehicle-photos/mno345.jpg" } } ``` | Position | What it shows | | --------- | ---------------------------------- | | `front` | The front of the vehicle | | `back` | The rear of the vehicle | | `right` | The right-hand side of the vehicle | | `left` | The left-hand side of the vehicle | | `chassis` | The chassis (VIN) number | ### Rules * **All five together.** A partial upload is rejected with a `422`. * **JPG or PNG, up to 3 MB each.** Other formats and anything larger are rejected. * **Once per vehicle.** The insurance provider keeps the first set it accepts; a second upload comes back as a `409`. Check the photos before sending them. * **Comprehensive only.** A `quote_price_id` belonging to a TPL quote is rejected. ## 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: The three quote identifiers must come from the response returned by the earlier `POST /quote-requests` call. Use the provider quote and price selected by the customer from that same response. | Field | Example Value | Description | | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `quote_request_id` | `62` | Use the top-level `id` from the quote request response. | | `quote_reference_id` | `feb9e0ec-d71c-4c60-99d4-22ad9a5c97ec` | Use `quotes[].quote_reference_id` from the insurance provider quote selected by the customer. | | `quote_price_id` | `f0a13788-92c3-f011-972d-005056a9891a` | Use `quotes[].prices[].quote_price_id` from the selected price and deductible inside the same provider quote. | | `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. It must belong to this customer. Do not reuse the same email address for different customers. | | `phone` | `0512345678` | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `iban` | `SA0380000000608010167519` | The customer's Saudi IBAN (`SA` followed by 22 digits, no spaces). It is sent to the insurance provider with the payment OTP request and used to transfer claim settlements and refunds to the customer; the account is never charged. Required. | 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": "someone@example.com", "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", "iban": "SA0380000000608010167519" } ``` The customer will receive a separate policy issuance OTP, and the API returns `204 No Content` on success. This OTP is valid for 15 minutes and must be supplied to the Issue Policy API within that period. If it expires, request a new issuance OTP before issuing the policy. The 8-hour quote OTP validity does not apply here. The policy issuance OTP expires after 15 minutes. ### Issuing a policy In order to Issue a policy. You can head to the Issue Policy API Use the same three identifiers previously sent to the Issue Policy OTP API. They must all come from the earlier `POST /quote-requests` response and represent one consistent customer selection. | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `quote_request_id` | Use the top-level `id` returned by the earlier `POST /quote-requests` call. | | `quote_reference_id` | Use `quotes[].quote_reference_id` from the insurance provider quote selected by the customer in that quote response. | | `quote_price_id` | Use `quotes[].prices[].quote_price_id` from the selected price and deductible inside the same provider quote. | | `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": "1234", "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": "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 | ### 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](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 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.