SME Medical Insurance

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.

Want to try it before writing code? Download the Postman collection, set your sandbox client_id and client_secret in its variables, and run it top to bottom.

Introduction

This guide walks you through integrating Yasmina’s SME Medical Insurance Price Comparison APIs into your platform (for the single-provider version, click here). These APIs let you retrieve and compare medical insurance packages from several insurance providers before issuing policies to a company’s employees. Using our secure and reliable endpoints, you’ll be able to request and manage policies, and issue claims. Everything you need to deliver insurance services seamlessly within your application.

Basic Journey

Authorize: Get an access token to authenticate all API requests.
Create a Company: Register the SME that will provide medical insurance for its employees.
Add the Employees: Save the company’s employees, each with the tier they want.
Get Prices: One request prices those employees with every insurance provider at once.
Issue the Policy: Pick a quote and issue the company’s policy from it.
Health Declarations: Get the declaration questions, download a printable form, or fill them in on the employees’ behalf.
Payment: Receive a secure payment link to finalize the purchase, and get the policy document once it clears.

Authorization

To access any of our API’s. You need to authorize yourself using the Generate Token API. We are using the standard OAuth 2.0 client credentials.
The Generate Token API requires client_id and client_secret. You can get these from your portal.
After making the request, you will get access_token in the response. The access_token must be used on all future Yasmina APIs and be supplied in the Authorization Header in the following form Authorization: Bearer {access_token}

For security reasons. Do not make your client_id and client_secret public in your platform.

Companies

Create a Company record

After acquiring an access_token, you can begin using the APIs. Before you produce policies for a company, you must create a company record. After creating the company record, you can request to issue policies to the employees of that company. The The Create Company API, will require a few fields that define details of the company such as Email, Phone, the company’s unified national number, a 10-digit sponsor number, and a 10-digit commercial registration number that starts with 7. It will return a response with a unique identifier (id). Here is an example of the response from the POST companies API.

{
  "name": "Example company name",
  "name_ar": "مثال اسم شركة",
  "sponsor_number": "1000000001",
  "unified_national_number": "7000000001",
  "email_address": "[email protected]",
  "phone_number": "+966512345678",
  "commercial_registration_number": "7000000002",
  "client_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "updated_at": "2025-08-01T14:22:30.000000Z",
  "created_at": "2025-08-01T14:22:30.000000Z",
  "id": 42
}

You can also visit the List companies API to show all companies you’ve created

Prices

Compare the packages

Every insurance provider sells the same four tiers, so an employee’s choice can be priced by all of them: basic, standard, premium and executive. What each provider puts inside a tier, and what it charges for it, is its own. The Categories API shows one provider’s tiers at a time; call it once per provider, passing insurance_provider as one of the values below, or omit it for MedGulf.

Insurance provider	`insurance_provider`
MedGulf (default)	`medgulf`
Walaa	`walaa`
Al-Rajhi Takaful	`alrajhi`
Tawuniya	`tawuniya`
Malath	`malath`

Each response carries the provider as insurance_provider and its display name as insurance_provider_name, then:

The Insurance provider PDF
- Contains an overview picture of what is provided by the Insurance provider
The translations
- The translations includes keys that map to the instructional text in Arabic and English that were provided by the insurance provider.
The categories
- One entry per tier, with the coverage values and the yearly price per person

Coverage values can either be a number (the amount), or a boolean (whether it’s covered or not), or a text (the type of coverage).

    "insurance_provider": "medgulf",
    "insurance_provider_name": "MedGulf",
    "medgulf_pdf": "https://...",
    "translations": { ... },
    "categories": {
        "basic": {
            "name": "Basic",
            "category": "basic",
            "insurance_provider": "medgulf",
            "price": 300,
            "maximum_annual_benefit_limit_per_person": 500000,
            "geography": "Saudi Arabia",
            "general_coverage": {
            ...
        }
        ...
    }

Add the employees

The Employees API holds the company’s employee list: who is covered, their dependents, and the tier each has picked. It prices nothing. Send the whole list; each call replaces the one before, and you can read it back at any time.

{
  "employees": [
    {
        "name": "John Doe",
        "nationality_iso": "SA",
        "category": "basic",
        "nationality_id": "1111111111",
        "mobile_number": "0500000001",
        "date_of_birth": "1409-09-14",
        "dependents": [
            {
                "name": "Jane Doe",
                "relationship": "spouse",
                "nationality_iso": "SA",
                "nationality_id": "1111111112",
                "date_of_birth": "1411-01-05"
            },
            {
                "name": "Jack Doe",
                "relationship": "child",
                "nationality_iso": "SA",
                "nationality_id": "1111111113",
                "date_of_birth": "1437-04-22"
            }
        ]
    },
    {
        "name": "Richard Roe",
        "nationality_iso": "JO",
        "category": "executive",
        "iqama_id": "2222222222",
        "mobile_number": "0500000002",
        "date_of_birth": "1988-04-20",
        "dependents": []
    }
  ]
}

John is Saudi (nationality_iso is SA), so we supply his nationality_id. Richard is not Saudi, so we supply his iqama_id instead. The API rejects the request if a Saudi employee has no nationality_id or a non-Saudi employee has no iqama_id. Every identifier, for employees and dependents alike, must be exactly 10 digits, and every employee needs a mobile_number.

Each employee’s category is one of the four tiers. Employees can be on different tiers.

Dependents

An employee can bring family members onto the policy through the dependents array. Each dependent needs a name, a relationship to the employee (spouse, child or parent), a nationality_iso, a date_of_birth, and the same identifier rule as the employee: a 10-digit nationality_id for Saudis, a 10-digit iqama_id for everyone else. Dependents do not carry their own mobile number. Dependents are covered under the employee’s tier; they cannot have one of their own. Leave the array out, or send it empty, for an employee with no dependents.

Dates of birth

Send every date_of_birth as YYYY-MM-DD. Saudi nationals whose national id starts with 1 give the Hijri (Umm al-Qura) date printed on their id, as John and his family do above; everyone else gives a Gregorian date. Employees must be between 18 and 110 years old; dependents can be any age.

Get prices from every provider

Call the Quote request API with the company_id and you get one response with a quote from every insurance provider, each priced for the employees saved above at the tiers they picked. Every quote carries a quote_price_id; the response itself carries an id, the quote_request_id. Keep both for the next step.

{
  "id": "a2bc93db-131e-4726-8a0a-0fed1da5ac0f",
  "company_id": 1,
  "employees": [ ... ],
  "quotes": [
    {
      "quote_price_id": "3fb4e3bb-6c7e-4a8f-9d2a-1b3c5d7e9f01",
      "insurance_provider": "medgulf",
      "insurance_provider_name": "MedGulf",
      "total_price": 1600,
      "currency": "SAR",
      "employees": [
        { "name": "John Doe", "identifier": "1111111111", "category": "basic", "dependents": 2, "price": 300 },
        { "name": "Richard Roe", "identifier": "2222222222", "category": "executive", "dependents": 0, "price": 1300 }
      ]
    },
    { "quote_price_id": "...", "insurance_provider": "walaa", "total_price": 1700, ... },
    ...
  ]
}

total_price is what the company pays for a year of cover with that provider, and the employees lines show where it comes from. A quote prices the employees as they stood when it was asked for; change the list and ask again.

Policies

Issue the policy

A company buys one policy, and its employees are the members on it, which is how the insurer issues it and how the policy document reads. Call the Issue policy API with the quote_request_id and the quote_price_id of the quote the company chose, and you get that one policy back: the provider that priced it, the quoted total as price, and every employee inside meta_data.insured.

{
  "quote_request_id": "a2bc93db-131e-4726-8a0a-0fed1da5ac0f",
  "quote_price_id": "3fb4e3bb-6c7e-4a8f-9d2a-1b3c5d7e9f01",
  "redirect_url": "https://www.example.com?yasmina_policy_id=policyID"
}

A company has one policy waiting to be paid for at a time. Issue again before payment, from a different quote if you like, and it is replaced. Once it is paid for, the next issue starts a new policy.

Health declaration forms

Insurers require a past medical history from every employee before they will cover them. Yasmina publishes the questions and prints the form; the company collects the answers itself, on paper or inside your own platform.

The questions: the Medical form API returns every question, grouped the way the insurers ask them, so you can build your own screen for it.
The printable form: the Download declaration form API returns the same declaration as a PDF. Pass a company_id and the file carries one page per employee you have already enrolled, with their name, id and package filled in, ready to print or email. Leave company_id out for a single blank form.

Filling them in for the employees: a company admin can answer on their behalf with the Fill medical forms API. It takes the company_id, all_employees, the default answers for everyone, and ids_or_emails, the employees whose answers differ. Name an employee by their nationality_id or iqama_id; one that matches nobody in the company is rejected. The answers are stored against each employee’s policy, and the response tells you how many are now declared and how many are still missing. For example, if nobody has had surgery except [email protected], declare No for past_surgeries under all_employees and override that one employee:

{
    "company_id": 1,
    "all_employees": {
        "allergies": "No",
        "current_medications": "No",
        "hospitalizations": "No",
        "pre_existing_conditions": "No",
        "past_surgeries": "No",
        "surgery_complications": "No",
        "chest_pain_or_breathlessness": "No",
        "heart_procedures": "No",
        "smoking": "No",
        "alcohol_consumption": "No",
        "physical_activity": "No",
        "family_history": "No",
        "chronic_disease": ["None of the above"]
    },
    "ids_or_emails": [
        {
            "id_or_email": "[email protected]",
            "answers": {
                "allergies": "No",
                "current_medications": "No",
                "hospitalizations": "No",
                "pre_existing_conditions": "No",
                "past_surgeries": "Yes",
                "surgery_complications": "No",
                "chest_pain_or_breathlessness": "No",
                "heart_procedures": "No",
                "smoking": "No",
                "alcohol_consumption": "No",
                "physical_activity": "No",
                "family_history": "No",
                "chronic_disease": ["Liver Disease"]
            }
        }
    ]
}

Payment

Every employee must have a health declaration on file before a company can pay. Ask for a payment link while any of them is missing one and the API answers 422, naming the employees still to declare.

Ask for the amount outstanding with the Payment due API. It answers with the sum of the premiums of that company’s policies that have not been issued yet, and every package’s price is in the categories response, so you can show the bill before anyone pays. Then get a link with the Payment link API and share it in your platform. It opens Yasmina’s secure card page, where the company pays for all of its employees in one go. The link is signed and expires after 15 minutes, so fetch it when the buyer is ready to pay rather than storing it. A company with nothing outstanding gets a 422 instead of a link.

Payment and Policy activation

When you first issue the policy, it 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, and the policy schedule listing every member becomes available through the List policies API.

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

Getting Started

Insurance Integration Guides

Build with AI

API Resources

Webhooks

White-labeling Solutions

Introduction

Basic Journey

Authorization

Companies

Create a Company record

Prices

Compare the packages

Add the employees

Dependents

Dates of birth

Get prices from every provider

Policies

Issue the policy

Health declaration forms

Payment

Payment and Policy activation

Redirect URL

​Introduction

​Basic Journey

​Authorization

​Companies

​Create a Company record

​Prices

​Compare the packages

​Add the employees

​Dependents

​Dates of birth

​Get prices from every provider

​Policies

​Issue the policy

​Health declaration forms

​Payment

​Payment and Policy activation

​Redirect URL

Introduction

Basic Journey

Authorization

Companies

Create a Company record

Prices

Compare the packages

Add the employees

Dependents

Dates of birth

Get prices from every provider

Policies

Issue the policy

Health declaration forms

Payment

Payment and Policy activation

Redirect URL