Create embed session

curl --request POST \
  --url https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "otp": "1234",
  "owner_id": "<string>",
  "email": "[email protected]",
  "phone": "<string>",
  "birthdate": "2023-12-25",
  "car_estimated_cost": 123
}
'

import requests

url = "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions"

payload = {
    "otp": "1234",
    "owner_id": "<string>",
    "email": "[email protected]",
    "phone": "<string>",
    "birthdate": "2023-12-25",
    "car_estimated_cost": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    otp: '1234',
    owner_id: '<string>',
    email: '[email protected]',
    phone: '<string>',
    birthdate: '2023-12-25',
    car_estimated_cost: 123
  })
};

fetch('https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'otp' => '1234',
    'owner_id' => '<string>',
    'email' => '[email protected]',
    'phone' => '<string>',
    'birthdate' => '2023-12-25',
    'car_estimated_cost' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions"

	payload := strings.NewReader("{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "quote_request_id": 42,
  "platform": "web",
  "embed_url": "https://.../embed?session=8TJLiR0YhE8ikWSH3N16br2Q4qDg0ozGu18c5c3E",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "code": "40101",
  "message": "Unauthenticated"
}

{
  "code": "<string>",
  "message": "<string>"
}

Create embed session

Requests quotes and opens an embeddable session on them in one call, and returns a URL to put in an iframe or a WebView. Takes everything Request Quotes takes, plus where the session will run.

The customer compares quotes, chooses add-ons, gives a payout account, uploads vehicle photos and verifies by OTP inside the embed. The issued policy and its payment link are handed back to your page or your app.

To show the quotes again after the hour is up, call this again with the same payload. The quote OTP stays valid for hours, so the customer is not asked to verify twice.

POST

embed-sessions

Create embed session

curl --request POST \
  --url https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "otp": "1234",
  "owner_id": "<string>",
  "email": "[email protected]",
  "phone": "<string>",
  "birthdate": "2023-12-25",
  "car_estimated_cost": 123
}
'

import requests

url = "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions"

payload = {
    "otp": "1234",
    "owner_id": "<string>",
    "email": "[email protected]",
    "phone": "<string>",
    "birthdate": "2023-12-25",
    "car_estimated_cost": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    otp: '1234',
    owner_id: '<string>',
    email: '[email protected]',
    phone: '<string>',
    birthdate: '2023-12-25',
    car_estimated_cost: 123
  })
};

fetch('https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'otp' => '1234',
    'owner_id' => '<string>',
    'email' => '[email protected]',
    'phone' => '<string>',
    'birthdate' => '2023-12-25',
    'car_estimated_cost' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions"

	payload := strings.NewReader("{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"otp\": \"1234\",\n  \"owner_id\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"<string>\",\n  \"birthdate\": \"2023-12-25\",\n  \"car_estimated_cost\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "quote_request_id": 42,
  "platform": "web",
  "embed_url": "https://.../embed?session=8TJLiR0YhE8ikWSH3N16br2Q4qDg0ozGu18c5c3E",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "code": "40101",
  "message": "Unauthenticated"
}

{
  "code": "<string>",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme

Body

application/json

otp

string

required

The OTP received by the customer from the Request OTP API

Pattern: ^\d{4}$

Example:

"1234"

owner_id

string

required

The owner's national ID (starts with 1 for Saudi nationals) or Iqama ID (starts with 2 for residents). Must be exactly 10 digits.

Pattern: ^(1|2)\d{9}$

string<email>

required

Email address must be valid and belongs to the customer

phone

string

required

Phone number must start with 05 and be 10 digits

Pattern: ^05\d{8}$

birthdate

string<date>

required

Birthdate in YYYY-MM-DD format

car_estimated_cost

number

required

Estimated cost of the car

platform

enum<string>

required

Where the session will run. web for an iframe, webview for a mobile app. There is no default: each one requires a different field below.

Available options:

web,

webview

car_sequence_number

string

Car sequence number must be 8 or 9 digits

Pattern: ^\d{8,9}$

custom_number

string

Customs card number between 100000 and 9999999999 for an imported vehicle. When provided, maker_code, model_code, and body_type_code are required, and car_sequence_number must be omitted.

Pattern: ^[1-9]\d{5,9}$

maker_code

integer

Required with custom_number. Use a code returned by GET /vehicle-makers.

Example:

101

model_code

integer

Required with custom_number. Use a code returned by GET /vehicle-models for the selected maker_code.

Example:

1001

body_type_code

integer

Required with custom_number. Use a code returned by GET /vehicle-body-types.

Example:

3

is_ownership_transfer

boolean

default:false

Indicates if the ownership is being transferred

current_car_owner_id

string

Required if is_ownership_transfer is true; the current owner's national ID (starts with 1) or Iqama ID (starts with 2). Must be exactly 10 digits.

Pattern: ^(1|2)\d{9}$

car_model_year

integer

Car model year between 1950 and next year

Required range: 1950 <= x <= 2026

start_date

string<date>

Desired policy start date in YYYY-MM-DD. Must be between tomorrow and 28 days from today (inclusive). The platform validates this range server-side.

Example:

"2025-12-11"

drivers

object[]

List of drivers for the vehicle. When provided, the sum of all driving_percentage values must equal 100, and the owner must be included among the drivers.

Hide child attributes

drivers.owner_id

string

required

Driver's national ID (starts with 1 for Saudi nationals) or Iqama ID (starts with 2 for residents). Must be exactly 10 digits.

Pattern: ^(1|2)\d{9}$

drivers.birthdate

string<date>

required

Driver's birthdate in YYYY-MM-DD format.

drivers.driving_percentage

enum<integer>

required

Percentage of driving for this driver. Valid values are 25, 50, 75, or 100. The sum of all drivers' percentages must equal 100.

Available options:

25,

50,

75,

100

Example:

[
  {
    "owner_id": "1234567890",
    "birthdate": "1990-01-15",
    "driving_percentage": 50
  },
  {
    "owner_id": "2345678901",
    "birthdate": "1985-06-20",
    "driving_percentage": 50
  }
]

parent_origin

string

Web only, and required there. The site the iframe will sit on: scheme and domain with nothing after it. Must be one of the iframe hosts registered in API Management. Prohibited for a webview, which has no origin.

Example:

"https://www.example.com"

deep_link

string

WebView only, and required there. Where your app is reopened once the policy is issued, with ?yasmina_policy_id= added. Must be one of the deep links registered in API Management. Prohibited for the web, which is handed the policy by postMessage instead.

Example:

"myapp://insurance/done"

locale

enum<string>

The language the embed opens in. Defaults to the customer's browser.

Available options:

ar,

en

Response

The session, with the URL to embed

integer

The session id, for reading it back later.

Example:

1

quote_request_id

integer

The quote request the embed was opened on. Yours to keep; you never send it back.

Example:

42

platform

enum<string>

What the session was opened for.

Available options:

web,

webview

embed_url

string

Put this in an iframe or a WebView. Belongs to one customer and expires after an hour.

Example:

"https://.../embed?session=8TJLiR0YhE8ikWSH3N16br2Q4qDg0ozGu18c5c3E"

expires_at

string<date-time>

When the URL stops working.

Authentication

SME Medical APIs

Motor Insurance APIs (Multiple Providers)

Property Insurance APIs

Travel Insurance APIs

Life (S&P) Insurance APIs

TPL Motor Insurance - Flat Fee APIs V2

Horse Insurance APIs

Payment

Create embed session

Authorizations

Body

Response