Instance: openIMIS (IO Sandbox)
Contents
- 1 Instance
- 2 Login
- 3 Description
- 4 1. How It Works ?
- 5 2. Access to the Platform
- 5.1 2.1 Base URL
- 5.2 2.2 Authentification
- 5.2.1 Authentication Flow
- 5.2.2 Request Header Format
- 6 3. Rules Common to All Requests
- 7 4. Available Resources
- 8 5. Query Details
- 8.1 5.1 Search for an Insuree (Patient)
- 8.2 5.2 List of Diagnoses
- 8.3 5.3 Searching for a Diagnosis
- 8.4 5.4 Procedures, Services, Medications, and Locations
- 8.4.1 Complete List
- 8.4.1.1 Retrieval by ID
- 8.4.1 Complete List
- 8.5 5.5 Submit a Claim
- 8.5.1.1 Request
- 8.5.1.2 Example body (request.json file)
- 8.5.2 Fields to Fill In
- 8.5.3 View a request
- 8.6 5.6 Tracking the Result of a Claim (ClaimResponse)
- 8.6.1 Response to a Request
- 8.6.2 Retrieving by ID
Login
URL | |
|---|---|
Admin | Admin : admin123 (English) |
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
Submit Credentials: Send a request containing the
usernameandpasswordof the eClaiming client account to the openIMIS authentication endpoint.Receive Token: Upon successful credential verification, the server responds with a JWT.
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
Claimresource).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 |
|---|---|---|
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
entryarray, with each element containing the resource atentry[].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 |
|---|---|---|
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 |
|---|---|---|---|
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 |
|---|---|---|
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.statusOnly 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.jsonExample 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 |
|---|---|---|
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"