Medical

​

Overview

The API’s in this documentation has been designed to seamlessly integrate with Yasmina’s platform, enabling a smooth and efficient exchange of medical insurance-related data and functionalities. Whether you’re looking to request or manage policies, handle claims, or access customer information, this API provides a robust and secure interface. With clear endpoints and comprehensive support, our goal is to simplify the integration process and ensure that our client can leverage the full potential of our insurance services with minimal effort.

​

Steps

Below is the basic journey to requesting your first insurance(s)

​

Authorization

To access any of our API’s. You need to authorize yourself. We are using OAuth 2.0 client credentials to achieve that.
You will need client_key and client_secret. You can get these from your portal.

After making the request, you will get access_token in the response. Example

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YmEyOTNmNy01ZjYyLTRlODItYmU5Yi1kODA0Y2M5ZDM5MmMiLCJqdGkiOiJlZWJjMWM5MWEyZThkMTVmNTYxNjZjMjkwM2Q0NTZjM2IzYWM5MTU5ZTdkODQ2YTE5NmFlYjcxMWM5OTJlMjc2MzAzNjY3MDA1MDQzM2U0OSIsImlhdCI6MTczNTkwNTE5OC40NTg5MiwibmJmIjoxNzM1OTA1MTk4LjQ1ODkyMSwiZXhwIjoxNzY3NDQxMTk4LjQ1Njk0LCJzdWIiOiIiLCJzY29wZXMiOltdfQ.Dy6df9fr4eBMLtkjnzcBjrXSg2AZLrmrBBC1NF8wmQaIOjcNffiqMiL9MqdMPj43Dxt4fj9rT1_S8dfwEpSbxNuIweNLOa7iDYpqMQ2l-cKG_sn24G27exZ9shLG8p2FHa4SHxSByRw00aCJceiTzq12LLNfc14rGPKZOv5Pi-HuLAP6ms_NfyN-KafOFOjYym4PyHCuTX8jEkoImgpBUpPgdnq1qyQdrZxL4grp0P_ezkhTgHgWwuzjSYgm4l-Eyga65kua-pdgWbhJ7-I1W_hjWT2dKCivcmk6nR9wtTjWs9hBvZrOfoZmox4YPIjZ_pvImZbHcZui-7xs80dnoaTKRviR8aot0cPIKoqRwinBodjWRh3QEu5juT1b7T-m85Wo_JNRoarKD4pW2Lzq7v1u9Z6PMEeYXvuFchzZ6HPvthblfwbtu3AX6ij0ZGlZPdMRdEiRtZf3dt8nsWdI-E_J0GAD-9wexlpNL92Z-IfuwMXuUQs_j4l92fcfBC_NxlEUTNACyOWPrA3V6ZSLHrga6W4Iz6Por3txzCsxlwvEBQAM70VyGeSqFi0wMLg2V8wVYAEpiEe2dl4RpMbUaPzRNc_KsDUYM_4DqwMTo2v2x4AAPxWmWiRn4PeAXovraN6Ll-eW9zq5hUbt3c-yj0spVYhJADHodoHmAdQM9MA"
}

Use the access_token and supply in the headers like this Authorization: Bearer <access_token>

Go to the following link to use the Authorization API.

​

Creating 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 POST companies API, will require few fields that define details of the company such as Email, Phone etc…

It will return a response with a unique identifier (id). Here is an example of the response from the POST companies API.

{
  "name": "Syarah",
  "name_ar": "شركة سيارة",
  "sponsor_number": "123",
  "email_address": "[email protected]",
  "phone_number": "+966551234567",
  "commercial_registration_number": "456",
  "client_id": "9c5b2b00-abcd-496c-a60b-8892fb63f0c3",
  "updated_at": "2024-07-15T20:36:12.000000Z",
  "created_at": "2024-07-15T20:36:12.000000Z",
  "id": 3
}

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

​

List available packages

After creating a company record, you can list available packages to the company. Check out the Categories API. This gives you a list of available insurance categories.

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
   • The categories items uses these keys and gives the coverage values

Each employee can have a separate package. 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) Each item in the categories has a category property. This is an important property as it is what you will need to provide when you issue policies. Notice the category field in the following sample of the categories response API.

    "categories": {
        "basic": {
            "name": "Basic",
            "category": "basic",
            "maximum_annual_benefit_limit_per_person": 500000,
            "geography": "Saudi Arabia",
            "general_coverage": {
            ...
        }
        ...
    }

​

Request insurance policies

To issue policies, you need to execute the Request policies API. The API takes two fields. The company_id as referenced above. And an array called insured. The insured are the employees that the company wants to request insurance for.policies Here is an example of a payload you would send

{
  "insured": [
    {
        "name": "Abdullah Enizi",
        "nationality_iso": "SA",
        "category": "basic",
        "iqama_id": "123",
        "date_of_birth": "1988-04-20",
        "number_of_dependents": 1
    },
    {
        "name": "Samer Najjar",
        "nationality_iso": "JO",
        "category": "standard",
        "nationality_id": "123",
        "date_of_birth": "1988-04-20",
        "number_of_dependents": 1
    }
  ],
  "company_id": 1
}

​

HR declaration forms

The companies that have requested insurance needs to be supply the insurance provider with Medical forms. These are mandatory for insurance providers to know past medical histories.

Yasmina offers two methods for submitting these forms:

1. Fill Medical Forms: Company administrators fill out the forms on behalf of the employees.

2. Dispatch Medical Forms: Company administrators dispatch the forms to employees, who then complete them individually.

Detailed explanations for each method are provided below.

​

Payment

Yasmina will supply a payment link of which your clients can pay for the insurance. You must share this link in your platform.