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.
Fetch the Employees: Get the employees registered under the company.
Edit the Employees: Change the list as needed, each employee with the tier they want.
Health Declarations: Get the declaration questions, download a printable form, and submit every employee’s answers under one consent.
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.
Payment: Read the policy for its payment link, share it, 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 and a 10-digit sponsor number. 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",
  "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": {
            ...
        }
        ...
    }

Fetch the employees

The Fetch employees API fills the company’s employee list with the employees registered under the company, each on the basic tier. It replaces the list, so fetch first and edit afterwards.

Edit 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. Employees can also carry sponsor_id (10 digits) and is_married (true or false), both optional. A non-Saudi whose iqama has not been issued yet sends a 10-digit border_number in place of iqama_id.

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.

Health declaration forms

Insurers require a past medical history from every employee before they will price them, so every employee declares before you ask for prices. Yasmina publishes the questions and prints the form; each employee answers for themselves, 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 the policy_id and the file carries one page per employee on the policy, with their name, id and package filled in, ready to print or email. Leave policy_id out for a single blank form.

Submitting the declarations: send every employee’s answers in one call with the Submit the declarations API. Each entry names an employee by their nationality_id, iqama_id or border_number as employee_id, and carries that employee’s own answers. One consent covers the whole submission and must be true, confirming the employees have stated that their answers are true and complete and agreed to share them with the insurance provider. Show that statement before submitting. The declarations are kept by employee id, apart from the employee list, so editing the list leaves them alone; each call replaces them, so send everyone each time. The response tells you who is still in pending_declarations, and prices are refused (40023) until everyone on the list has declared.

PUT /medical/companies/42/declarations
{
    "consent": true,
    "employees": [
        {
            "employee_id": "1111111111",
            "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"]
            }
        },
        {
            "employee_id": "2222222222",
            "answers": { ... }
        }
    ]
}

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,
      "price_per_employee": 800,
      "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 }
      ],
      "packages": {
        "basic": {
          "name": "Basic",
          "price": 300,
          "benefits": { "maximum_annual_benefit_limit_per_person": 500000, "general_coverage": { ... }, ... },
          "network": {
            "name": "MG6",
            "total": 1132,
            "facilities": { "hospital": 230, "pharmacy": 4, "clinic": 611, "optical": 24, "other": 263 },
            "provider_list_url": "https://api.yasmina.ai/api/v1/medical/products/networks?insurance_provider=medgulf&category=basic"
          }
        },
        "executive": { ... }
      }
    },
    { "quote_price_id": "...", "insurance_provider": "walaa", "total_price": 1700, ... },
    ...
  ]
}

total_price is what the company pays for a year of cover with that provider, price_per_employee is that total divided by the number of employees, and the employees lines show where it comes from. packages has one entry per tier the employees picked, with its benefits (the coverage values from the Categories API) and its network. A quote prices the employees as they stood when it was asked for; change the list and ask again. Benefits and networks differ by tier, not just by provider: a higher tier reaches more facilities and buys a better room, a higher copayment cap and higher pregnancy and vision limits. Show them side by side so the company can see what each tier adds. The network gives the facility counts by type for a comparison table; its provider_list_url is the Networks API call that lists every facility in that tier with its status, included or referral, and the cities to filter by.

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.

Payment

Everything needed to take payment is on the policy object. Read the policy and you get:

price: what the company pays for a year of cover.
pending_declarations: the employees who still have to declare their medical history. Everyone declared before the prices, so it is empty.
payment_link: where the company pays, once pending_declarations is empty. It opens Yasmina’s secure card page, where the company pays for all of its employees in one go. It is a fresh signed link on every read and expires after 15 minutes, so read the policy when the buyer is ready to pay rather than storing the link. It is null while anyone still has to declare, and again once the policy is issued.

The policy returned by issuing and by filling the declarations carries the same fields, so in the simplest flow you issue, fill, and send the customer to the link on the response.

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

Fetch the employees

Edit the employees

Dependents

Dates of birth

Health declaration forms

Get prices from every provider

Policies

Issue the policy

Payment

Payment and Policy activation

Redirect URL

​Introduction

​Basic Journey

​Authorization

​Companies

​Create a Company record

​Prices

​Compare the packages

​Fetch the employees

​Edit the employees

​Dependents

​Dates of birth

​Health declaration forms

​Get prices from every provider

​Policies

​Issue the policy

​Payment

​Payment and Policy activation

​Redirect URL

Introduction

Basic Journey

Authorization

Companies

Create a Company record

Prices

Compare the packages

Fetch the employees

Edit the employees

Dependents

Dates of birth

Health declaration forms

Get prices from every provider

Policies

Issue the policy

Payment

Payment and Policy activation

Redirect URL