> ## 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. # SME Medical Insurance > Compare SME medical insurance packages from multiple providers, issue policies for employees, and collect their health declarations.

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](https://docs.yasmina.ai/postman/sme-medical-insurance.postman_collection.json), 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](/single-provider-integrations/sme-medical-insurance)). 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 1. **Authorize**: Get an access token to authenticate all API requests. 2. **Create a Company**: Register the SME that will provide medical insurance for its employees. 3. **Add the Employees**: Save the company's employees, each with the tier they want. 4. **Get Prices**: One request prices those employees with every insurance provider at once. 5. **Issue the Policy**: Pick a quote and issue the company's policy from it. 6. **Health Declarations**: Get the declaration questions, download a printable form, or fill them in on the employees' behalf. 7. **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](https://portal.yasmina.ai/api-management).
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": "example@example.com", "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](/medical-api-reference/company/list-companies) 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](/medical-api-reference/products/list-categories) 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: 1. The Insurance provider PDF * Contains an overview picture of what is provided by the Insurance provider 2. The translations * The translations includes **keys** that map to the instructional text in Arabic and English that were provided by the insurance provider. 3. 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](/medical-api-reference/employees/save-the-employees) 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](/medical-api-reference/quotes/get-prices-from-every-provider) 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](/medical-api-reference/policies/issue-the-policy) 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. 1. **The questions**: the [Medical form API](/medical-api-reference/medical-forms/get-the-medical-form-questions) returns every question, grouped the way the insurers ask them, so you can build your own screen for it. 2. **The printable form**: the [Download declaration form API](/medical-api-reference/medical-forms/download-the-declaration-form) 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. 3. **Filling them in for the employees**: a company admin can answer on their behalf with the [Fill medical forms API](/medical-api-reference/medical-forms/fill-medical-forms). 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 [john.doe@example.com](mailto:john.doe@example.com), 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": "john.doe@example.com", "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](/medical-api-reference/payment/payment-due). 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](/medical-api-reference/payment/payment-link) 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](/medical-api-reference/policies/list-policies). 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)