Overview
This guide walks you through integrating Yasmina’s Medical Insurance API into your platform (for Multiple Insurance Providers with package comparison, click here). 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.
- Choose a Package: Retrieve and review available medical insurance packages.
- Issue Insurance: Select the employees who will be covered and create their policies.
- Health Declarations: Complete forms on behalf of employees or send them directly for completion.
- Payment: Receive a secure payment link to finalize the purchase.
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. Example
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}
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.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.- 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
- The categories items uses these keys and gives the coverage values
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.
Issue insurance policies
To issue policies, you need to execute the Issue policy API. The API takes three fields. The company_id as referenced above, the insurance_provider (medgulf for this integration), and an array called insured. The insured are the employees that the company wants to issue insurance for.
Here is an example of a payload you would send
Notice in the above, there are two employees within the company. 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.category that we are supplying is what was returned from the Categories API
Dependents
An employee can bring family members onto the policy through thedependents 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: nationality_id for Saudis, iqama_id for everyone else. Dependents are covered by the employee’s provider and category; they cannot have a package of their own. Leave the array out, or send it empty, for an employee with no dependents.
Dates of birth
Send everydate_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.
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 ways to collect them:- Fill Medical Forms: Company administrators fill out the forms on behalf of the employees.
- Download the form: Get a printable PDF and send it to the employees yourself.
Fill medical forms
Fill medical forms
The fill medical forms allows the company admin to do so on behalf of the employers of the company. It takes two fields of which both are objects Check out the Fill medical forms API docs for all the supported props.
all_employees and ids_or_emails.The idea behind the two fields, is to allow the Company admin to select the default answers for all employees, and then override the answers for specific employees.For example, let us say that all employees except 1 (for example employee with email [email protected]), never had surgeries before, we can declare the answer No on the surgery question in the all_employees field, but declare Yes for the other employee.employeeHere’s an example of such caseDownload the form
Download the form
The Download declaration form API returns the declaration as a PDF. Pass the
company_id and the file carries one page per employee you have already enrolled, with their name, id and package filled in, so the company can print it or email it on. Leave company_id out and you get a single blank form.