Instance: openIMIS (IO Sandbox)

Instance: openIMIS (IO Sandbox)

Contents

Instance

Package

openIMIS

Line

IO Sandbox

Version

Release 2026-04

Status

UP

Server

S2

Database

PostgreSQL

 

Login

URL

http://openimis.s2.openimis.org/

Admin

Admin : admin123 (English)
Admin_Fr : admin123 (French)

User

 

Other

 

Instructions

 

Description


This guide explains to technical teams working with electronic medical record (EMR) systems how to query the National Health Interoperability Platform to exchange data with openIMIS, the CSU’s health insurance management system in Cameroon.

It describes how to access the platform, the authentication process, the rules common to all requests, and then each available request along with a ready-to-use example.

Target Audience

  • The technical EMRs (Electronic Medical Records) team responsible for connecting their software to the platform.

  • Anyone testing data exchanges, for example using Postman or curl.

What the Platform Enables

  • Search for an insured person and verify their information.

  • Retrieve openIMIS data sets: diagnoses, procedures and services, medications and supplies, and locations.

  • Submit a reimbursement request (Claim) for a covered insured person.

  • Track the status of this request (ClaimResponse).

Credentials creation

Each third party can create users with dedicated rights (per Health Facility / etc… ) directly in openIMIS admin (admin access provided)

1. How It Works ?

Data exchanges use the HL7 FHIR R4 standard in JSON format. Resources, their fields, and their codes follow the openIMIS FHIR implementation guide.

You will find more details about FHIR documentation here : https://fhir.openimis.org/

You may find tutorial here : https://fhirdoc.s2.openimis.org/#overview

2. Access to the Platform

2.1 Base URL

All requests are sent via HTTPS to the following address, followed by the resource path:

https://openimis.s2.openimis.org/api/api_fhir_r4/

The full path for each request is listed in the table in Section 5.

Examples: the search for insured individuals is performed at https://openimis.s2.openimis.org/api/api_fhir_r4/Patient , and the list of diagnoses is available at https://openimis.s2.openimis.org/api/api_fhir_r4/CodeSystem/diagnosis.

2.2 Authentification

To send or manage claims through openIMIS FHIR R4 APIs, your system must first acquire a valid JWT. This token serves as a digital credential, verifying the identity and permissions of the requesting system.

Authentication Flow

  1. Submit Credentials: Send a request containing the username and password of the eClaiming client account to the openIMIS authentication endpoint.

  2. Receive Token: Upon successful credential verification, the server responds with a JWT.

  3. Attach Token: Include this JWT in the HTTP headers of all subsequent requests made to protected openIMIS FHIR R4 endpoints (such as submitting a FHIR Claim resource).

  4. Token Refresh/Re-authentication: Inspect the exp (expiration) claim inside the token payload. Once expired, the client application must re-authenticate to obtain a new token before making further API requests.

https://openimis.s2.openimis.org/api/api_fhir_r4/login/

Request Header Format

Include the JWT in the Authorization HTTP header for all protected API calls:

Authorization: Bearer <your_jwt_token>

3. Rules Common to All Requests

3.1 HTTP Headers

Header

Value

When

Header

Value

When

Authorization

Custom <YOUR_TOKEN>

Always

Accept

application/json

Always

Content-Type

application/json

For requests with a body (POST)

3.2 Response Format

  • A search returns an FHIR Bundle: the list of results is contained in the entry array, with each element containing the resource at entry[].resource.

  • A query by identifier returns the requested resource directly.

  • In most cases, an error returns an OperationOutcome resource whose issue[].details.text field describes the problem.

3.3 HTTP Response Codes

Code

Meaning

What to do

Code

Meaning

What to do

200

Request processed

Read the response.

201

Resource created

Save the returned ID for tracking.

400

Invalid request: missing field, incorrect format, or business rule violation

Read the OperationOutcome message and correct the request

401

Token missing, invalid, or unauthorized access to this resource

Check the Authorization header

404

Resource Not Found

Check the ID or path you used.

405

Unauthorized method on this path

Check the HTTP method (GET, POST)

500, 502, 503

Error or platform service unavailability

Please try again later

4. Available Resources

The following table summarizes the requests available to EMRs. The paths should be appended to the base URL.

Requirement

FHIR Resources

Request

Section

Requirement

FHIR Resources

Request

Section

Search for an Insuree

Patient

GET /Patient?identifier=…

5.1

List of Diagnoses

CodeSystem (diagnostics)

GET /CodeSystem/diagnosis

5.2

Search for a Diagnoses

CodeSystem (diagnostics)

GET /CodeSystem/diagnosis/<code>

5.3

List of Procedures and Services

ActivityDefinition

GET /ActivityDefinition

5.4

An act or service

ActivityDefinition

GET /ActivityDefinition/<id>

5.4

List of Medications and Supplies

Medication

GET /Medication

5.4

A medication or supply

Medication

GET /Medication/<id>

5.4

List of Locations

Location

GET /Location

5.4

Submit Claim

Claim

POST /Claim

5.5

View a claim

Claim

GET /Claim/<id>

5.5

Request Result from a claim

ClaimResponse

GET /ClaimResponse?request=Claim/<id>

5.6

Request a specific result

ClaimResponse

GET /ClaimResponse/<id>

5.6

5. Query Details

In the examples, replace the values between angle brackets (<…>) with your own values.

5.1 Search for an Insuree (Patient)

Allows you to find an insured person using their insured person number (for example, upon admission) to verify their identity and retrieve their identifier (UUID) in openIMIS.

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/Patient?identifier=<INSUREE_CODE>" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"

Answer: a Bundle. If the insured person exists, they appear in entry[0].resource. Their id field contains the UUID to be included in reimbursement requests (patient field).

 

INSUREE NOT FOUND

If the Bundle contains no elements (total equals 0 or the “entry” array is missing), the number entered does not correspond to any insured person: verify the number with the patient before submitting any reimbursement request.

5.2 List of Diagnoses

Returns the list of diagnoses recognized by openIMIS. The codes in this list are the only ones accepted in reimbursement requests (diagnosis field).

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/CodeSystem/diagnosis" \   -H "Authorization: Custom <VOTRE_JETON>" \   -H "Accept: application/json"

Answer: A CodeSystem resource. Each diagnosis is listed in the concept table, along with its code and label.

5.3 Searching for a Diagnosis

Returns a specific diagnosis based on its code, for example, to verify that a code entered in the EMR is correctly recognized by openIMIS before using it in a reimbursement request (diagnosis field).

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/CodeSystem/diagnosis/<CODE_DIAGNOSTIS>" \ -H "Authorization: Custom <YOUR_TOKEN>" \ -H "Accept: application/json"

Response: A CodeSystem resource whose concept array contains only the requested diagnosis, along with its code and display name. The content field is set to “fragment,” and the count field is set to 1.

If the code is unknown, the response is a 404 error in the OperationOutcome format: the code must not be used in a reimbursement request.

Case sensitivity does not matter for the code: jb20 and JB20 return the same diagnosis

5.4 Procedures, Services, Medications, and Locations

These reference sets provide the identifiers and codes to be used in the lines of reimbursement claims.

Repository

Resource

Use in a Request

Repository

Resource

Use in a Request

Medical Procedures and Services

ActivityDefinition

Service-type row: ActivityDefinition/<id> reference and code in productOrService

Medications and supplies

Medication

Item-type line: Medication/<id> reference and code in productOrService

Locations (regions, districts, etc.)

Location

Context information

Complete List

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/ActivityDefinition?_count=20&page-offset=1" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"

Example Response:

{ "resourceType": "Bundle", "type": "searchset", "total": 95, "link": [ { "relation": "self", "url": "http://localhost:8000/api/api_fhir_r4/ActivityDefinition/?_count=20&page-offset=1" }, { "relation": "next", "url": "http://localhost:8000/api/api_fhir_r4/ActivityDefinition/?_count=20&page-offset=2" } ], "entry": [ { "fullUrl": "http://localhost:8000/api/api_fhir_r4/ActivityDefinition/de60ca2f-d2d8-4f4e-9f08-f3f718a6fb77", "resource": { "resourceType": "ActivityDefinition", "id": "de60ca2f-d2d8-4f4e-9f08-f3f718a6fb77", "identifier": [ { "type": { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers", "code": "UUID" } ] }, "value": "de60ca2f-d2d8-4f4e-9f08-f3f718a6fb77" }, { "type": { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers", "code": "Code" } ] }, "value": "M1" } ], "name": "M1", "title": "OBG Cervical Cerclage - Shrodikar", "status": "active", "date": "2017-01-01T00:00:00", "topic": [ { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/activity-definition-service-type.html", "code": "C", "display": "Curative" } ] } ], "extension": [ { "url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/unit-price", "valueMoney": { "value": 21000, "currency": "$" } } ] } } ] }

Retrieval by ID

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/ActivityDefinition/<UUID_SERVICE>" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"

The same requests apply to Medication (replace ActivityDefinition with Medication) and, for the list only, to Location, whose path is /api/fhir/openimis/Location. A search returns a Bundle; a read by identifier returns the resource directly, or a 404 error if the identifier is unknown.

Medication example:

GET /api/api_fhir_r4/Medication/ Example: curl -u Admin:admin123 \ -H "Accept: application/json" \ "http://localhost:8000/api/api_fhir_r4/Medication/?_count=20&page-offset=1"

Example response:

{ "resourceType": "Bundle", "type": "searchset", "total": 258, "link": [ { "relation": "self", "url": "http://localhost:8000/api/api_fhir_r4/Medication/?_count=20&page-offset=1" }, { "relation": "next", "url": "http://localhost:8000/api/api_fhir_r4/Medication/?_count=20&page-offset=2" } ], "entry": [ { "fullUrl": "http://localhost:8000/api/api_fhir_r4/Medication/1297627a-e45c-4f78-84bd-15c4981b770b", "resource": { "resourceType": "Medication", "id": "1297627a-e45c-4f78-84bd-15c4981b770b", "identifier": [ { "type": { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers", "code": "UUID" } ] }, "value": "1297627a-e45c-4f78-84bd-15c4981b770b" }, { "type": { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers", "code": "Code" } ] }, "value": "0005" } ], "code": { "text": "AIRWAY GUEDEL RUBBER SMALL ADULT SIZE 82 MM" }, "status": "active", "form": { "text": "10 PIECES" }, "amount": { "numerator": { "value": 10 } }, "extension": [ { "url": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/unit-price", "valueMoney": { "value": 4590, "currency": "$" } }, { "url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/medication-type", "valueCodeableConcept": { "coding": [ { "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/medication-item-type", "code": "D", "display": "Drug" } ] } } ] } } ] }

An item can be retrieved by UUID or openIMIS item code.

By UUID: GET /api/api_fhir_r4/Medication/{UUID}/ curl -u Admin:admin123 \ -H "Accept: application/json" \ "http://localhost:8000/api/api_fhir_r4/Medication/1297627a-e45c-4f78-84bd-15c4981b770b/" By item code: GET /api/api_fhir_r4/Medication/{ITEM_CODE}/ curl -u Admin:admin123 \ -H "Accept: application/json" \ "http://localhost:8000/api/api_fhir_r4/Medication/0005/"

Item field Mapping:

## Item field mapping openIMIS field FHIR field ━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Item UUID Medication.id and UUID identifier ────────────────────── ──────────────────────────────────── Item code Code identifier ────────────────────── ──────────────────────────────────── Item name Medication.code.text ────────────────────── ──────────────────────────────────── Package Medication.form.text ────────────────────── ──────────────────────────────────── Package quantity Medication.amount.numerator.value ────────────────────── ──────────────────────────────────── Price Unit-price extension ────────────────────── ──────────────────────────────────── Item type Medication-type extension ────────────────────── ──────────────────────────────────── Frequency Medication-frequency extension ────────────────────── ──────────────────────────────────── Patient category Medication usage-context extension ────────────────────── ──────────────────────────────────── Care type Medication usage-context extension ────────────────────── ──────────────────────────────────── Active/current state Medication.status

Only currently valid items are returned by the normal collection request.

5.5 Submit a Claim

A reimbursement claim describes the care provided to an insured person: the period, the diagnosis, and each procedure or medication billed.

Request

curl -s -X POST "https://openimis.s2.openimis.org/api/api_fhir_r4/Claim" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Content-Type: application/json" \   -H "Accept: application/json" \   -d @demande.json

Example body (request.json file)

{   "resourceType": "Claim",   "identifier": [{     "type": { "coding": [{       "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",       "code": "Code" }] },     "value": "<CODE_DEMANDE>"   }],   "status": "active",   "type": { "coding": [{     "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-visit-type",     "code": "O", "display": "Other" }] },   "use": "claim",   "patient": { "reference": "Patient/<UUID_INSUREE>" },   "billablePeriod": { "start": "2026-09-30", "end": "2026-09-30" },   "created": "2026-09-30",   "enterer": { "reference": "Practitioner/<UUID_CLAIMADMIN>" },   "provider": { "reference": "Organization/<UUID_HEALTHFACILITY>" },   "priority": { "coding": [{     "system": "http://terminology.hl7.org/CodeSystem/processpriority",     "code": "normal" }] },   "diagnosis": [{     "sequence": 1,     "diagnosisCodeableConcept": { "coding": [{       "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/diagnosis-ICD10-level1",       "code": "<CODE_DIAGNOSTIC>" }] }   }],   "insurance": [{     "sequence": 1, "focal": true,     "coverage": { "reference": "Coverage/<UUID_COVERAGE>" }   }],   "item": [{     "extension": [{       "url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",       "valueReference": { "reference": "ActivityDefinition/<UUID_SERVICE>" }     }],     "sequence": 1,     "category": { "text": "service" },     "productOrService": { "text": "<SERVICE_CODE>" },     "quantity": { "value": 1 },     "unitPrice": { "value": 200, "currency": "EUR" }   }],   "total": { "value": 200, "currency": "EUR" } }

Fields to Fill In

Fielr

Content

Source

Fielr

Content

Source

identifier

Unique request code, with the “Code” type. A code that has already been used is rejected.

Generated by EMR

patient

Patient/<INSUREE UUID>

Searching for Insuree (5.1)

billablePeriod, created

Dates of Care and Claim Creation (YYYY-MM-DD)

EMR

enterer

Practitioner/<CLAIMADMIN_UUID>

Submitted separately

provider

Organization/<HEALTH FACILITY UUID>

Submitted separately (4)

diagnosis

Primary diagnosis code

Diagnosis list (5.2)

insurance.coverage

Coverage/<UUID Coverage of INSUREE>

Insured person's record in openIMIS

item[].extension

Procedure ID (ActivityDefinition/<id>) or Medication ID (Medication/<id>)

Data Models (5.4)

item[].category.text

Service for a procedure, item for a medication or supply

Line type

item[].productOrService.text

Procedure or Medication Code

Data Models (5.4)

item[].quantity, unitPrice

Quantity and unit price in Currency

EMR

total

Sum of lines (quantity × unit price)

Calculated by the EMR

 

Response: If successful, the request is created, along with its identifier (id field). Save this identifier to track the request (section 5.6).

View a request

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/Claim/<UUID_CLAIM>" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"

5.6 Tracking the Result of a Claim (ClaimResponse)

After being processed by openIMIS, each claim receives a response (ClaimResponse) indicating its status and the approved amounts.

Response to a Request

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/ClaimResponse?request=Claim/<UUID_CLAIM>" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"

Retrieving by ID

curl -s "https://openimis.s2.openimis.org/api/api_fhir_r4/ClaimResponse/<UUID_RESPONSE>" \   -H "Authorization: Custom <YOUR_TOKEN>" \   -H "Accept: application/json"