Overview

The Healthstack API gives you access to all the core features available on our dashboard and allows you to integrate them directly into your healthtech applications. It follows REST principles and is organized around key healthcare resources such as patients, medical records, consent, and Medicard — with a few specialized endpoints for advanced use cases.

Base URL: https://api.healthstack.ng/v1

🔐 Secure Authentication

JWT-based authentication with access and consent tokens for secure data access.

👥 Patient Identity

Centralized patient management using NIN for unique identification across all healthcare providers.

📋 Consent Management

Strict consent-based access control ensuring patient data privacy and compliance.

🏥 Tier-Based Access

KYC-based tier system controlling access levels for different types of healthcare businesses.

Key Concepts

Core Identifiers

NIN (National Identification Number)

Government-issued unique identifier used to identify patients across all healthcare systems.

HealthID

HealthStack-generated unique patient identifier in format HID-XXXXXXXX.

Authentication Tokens

Token Purpose Validity Header
Secret Key API authentication - - Authorization: Bearer
ConsentToken Patient data access 24 hours x-consent-token

Patient Management

POST /patients/create
Create a new patient or fetch existing patient by NIN. This step is required before requesting consent.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{
    
    "name": Jane Doe,
    "gender": female,
    "dob": 1990-01-01,
    "nin": 12345678901,
    "email": jane.doe@email.com,
    
    
}

Request Body Parameters

Parameter Type Required Description
name string Yes Full name of the patient
gender string Yes Patient's gender (male/female/other)
dob string Yes Date of birth in ISO format (YYYY-MM-DD)
nin string Yes National Identification Number (11 digits)
email string Yes Patient's email address

Response

Response Body Parameters 
{
    
    "status": true,
    "message": "Patient created successfully",
    "data": {
        "health_id": "HID-PSE8RUOK",
        "name": "Jane Doe",
        "nin": "12345678901",
        "email": "jane.doe@email.com",
        "created_at": "2024-01-15T10:30:00Z"
    },
    
}

Response Parameters

Parameter Type Description
status boolean Indicates whether the request was successful
message string Descriptive message about the operation result
data.health_id string Unique patient identifier generated by HealthStack
data.name string Full name of the patient
data.nin string National Identification Number
data.email string Patient's email address
data.created_at string Timestamp of patient record creation in ISO format
POST /patients/seek-consent
Send verification code to patient's email or phone for consent.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{
    "health_id": HID-PSE8RUOK,
}

Request Body Parameters

Parameter Type Required Description
health_id string Yes Unique patient identifier in format HID-XXXXXXXX

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "A verification OTP has been sent your user for consent",
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the request was successful
status boolean Indicates whether the consent was successfully granted
message string Descriptive message about the consent operation
POST /patients/consent
Verify OTP and receive consent token for patient data access.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{
    "health_id": HID-NHG869UP,
    "otp": 123456,
}

Request Body Parameters

Parameter Type Required Description
health_id string Yes Unique patient identifier in format HID-XXXXXXXX
otp integer Yes 6-digit One-Time Password received by patient

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Consent token assigned successfully",
    "data": {
        "consentToken": "eyJhbGciOiJIUzI1Ni...",
        "health_id": "HID-NHG869UP", 
    },
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the request was successful
status integer Indicates the status of the request
message string Descriptive message about the consent operation
data.consentToken string Unique token for accessing patient data
data.health_id string Unique patient identifier in format HID-XXXXXXXX
GET /patients/multiple
Get all patients created by a business.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Patients fetched successfully",
    "data": [
        {
            "id": "424077c6-e3ba-42e8-af79-783229333928",
            "full_name": "Gift Amadi",
            "gender": "Female",
            "dob": "2018-06-16",
            "health_id": "HID-NHG869UP",
            "created_at": "2025-07-16T10:07:20.413641+00:00",
            "email": "aminigbopaul@gmail.com",
            "business_id": "BUS-AFV2LA01",
            "updated_at": "2025-07-16T10:07:20.413641+00:00",
            "metadata": {
                "key": "value"
            }
        },
        ...
    ],
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the request was successful
status integer Indicates the status of the request
message string Descriptive message about the consent operation
data.id string Unique patient identifier in format HID-XXXXXXXX
data.full_name string Full name of the patient
data.gender string Gender of the patient
data.dob string Date of birth of the patient
data.health_id string Unique patient identifier in format HID-XXXXXXXX
data.created_at string Date and time the patient was created
data.email string Email of the patient
data.business_id string Business identifier in format BUS-XXXXXXXX
data.updated_at string Date and time the patient was updated
data.metadata object Metadata of the patient
data.metadata.key string Key of the metadata
GET /patient/single/:health_id
Note:Consent token is required to get a record for patients you did not create.
This endpoint is used to get user's record by user health id.

Headers

Authorization: Bearer sk_test_1234567890abcdef
x-consent-token: ct_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Patient fetched successfully",
    "data": [
        "id": "424077c6-e3ba-42e8-af79-783229333928",
        "full_name": "Gift Amadi",
        "gender": "Female",
        "dob": "2018-06-16",
        "health_id": "HID-NHG869UP",
        "created_at": "2025-07-16T10:07:20.413641+00:00",
        "email": "aminigbopaul@gmail.com",
        "business_id": "BUS-AFV2LA01",
        "updated_at": "2025-07-16T10:07:20.413641+00:00",
        "metadata": {},
        "vital": null 
    ],
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the request was successful
status integer Indicates the status of the request
message string Descriptive message about the consent operation
data.id string Unique record identifier in format
data.full_name string Full name of the patient
data.gender string Gender of the patient
data.dob string Date of birth of the patient
data.health_id string Unique patient identifier in format HID-XXXXXXXX
data.created_at string Date and time the patient was created
data.email string Email of the patient
data.business_id string Business identifier in format BUS-XXXXXXXX
data.updated_at string Date and time the patient was updated
data.vital object Vital of the patient
data.metadata object Metadata of the patient
data.metadata.key string Key of the metadata
PATCH /edit/:health_id
Note:Consent token is required to get a record for patients you did not create.
This endpoint is used to edit user's record by user health id.

Headers

Authorization: Bearer sk_test_1234567890abcdef
x-consent-token: ct_1234567890abcdef

Request Body

Request Body Parameters 
{
   Key: Value
}

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Patient fetched successfully",
    "data": {
       "metadata": 
            {
               Key: Value
            }
       ,
    },
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the request was successful
status integer Indicates the status of the request
message string Descriptive message about the consent operation
data object Data of the request
data.metadata object Metadata of the request
data.metadata.key string Key of the metadata

Medical Records

Note: Medical records are immutable once created.
POST /records
Create a new medical record for a patient. Requires valid consent token for patients you did not create.

Headers

Authorization: Bearer sk_test_1234567890abcdef x-consent-token: ct_1234567890abcdef

Request Body

Request Body Parameters 
{
    "recordType": diagnosis,
    "data": {
        "diagnosis": "Fever",
        "severity": "Mild",
        "notes": "Patient reported mild fever"
    },
    "patient": HID-NHG869UP,,
    
}

Request Body Parameters

Parameter Type Required Description
recordType string Yes Type of medical record (diagnosis, prescription, lab, clinical_note)
data object Yes Record-specific details based on record type
provider object Yes Healthcare provider information
provider.name string Yes Name of the healthcare provider/institution
provider.nprn string Yes National Provider Registration Number
Response Body Parameters 
{
    "success": true,
    "status": true,
    "message": "Medicard created successfully",
    "data": {
            "recordId": "454e23a2-4e56-4e9f-902c-6b38d59dadf6",
            "patient": "HID-NHG869UP", 
            "created_at": "2025-07-22T11:58:58.058435+00:00"
    }
    
}

Supported Record Types

Diagnosis

"data": {
"diagnosis": "Fever",
"severity": "Mild",
"notes": "Note..."
}

Prescription

"data": {
"medications": [
{
    "dosage": "480mlg",
    "drugName": "Artemeter ",
    "duration": "3 days",
    "frequency": "twice daily"
}
],
"prescribedAt": "2025-07-18T09..",
"prescribedBy": "Dr. Michael"
}

Lab Results

"data": {
"labName": "Lifeline Clinic",
"testType": "Blood group",
"testedAt": "2025-07-18T09..",
"parameters": [
    {
    "name": "SDDH-3",
    "value": "21",
    "normalRange": "21"
    }
]
}

Vital Signs

"data": {
"heartRate": "76bpm",
"measuredAt": "2025-07-18T06..",
"temperature": "37",
"bloodPressure": "100/80",
"respiratoryRate": "18 b/m"
}

Consultation

"data": {
"date": "2025-07-19T18..",
"notes": "Note...",
"purpose": "General check-up",
"duration": "20 mins",
"consultedBy": "Dr. Michael" 
}

Imaging

"data": {
"findings": "Our findings",
"scanType": "Chest X-ray",
"attachments": [
    {
    "fileUrl": "https://jknvfkr dm",
    "fileName": "Image"
    }
],
"performedAt": "2025-08-13T20.."
}

Surgery

"data": {
"surgeon": "Dr. John",
"procedure": "Appendix",
"surgeryDate": "2025-08-30T00..",
"surgicalNotes": "Surgical Note..."
}

Allergy

"data": {
"notedAt": "2025-08-21T00:00:00.000Z",
"reaction": "Rash",
"severity": "Moderate",
"substance": "Paracetamol"
}

Vaccination

"data": {
"date": "2025-08-22T00:00:00.000Z",
"dose": "1st",
"vaccine": "COVID-19",
"administeredBy": "Nurse Mary"
}

Admission

"data": {
"wardUnit": "Room 23",
"admissionDate": "2025-08-15T00..",
"admissionNotes": "Additional Note",
"admissionReason": "Acute Malaria",
"admittingPhysician": "Dr. John"
}

Discharge

"data": {
"dischargeDate": "2025-08-22T00..",
"dischargeStatus": "Recovered",
"dischargingPhysician": "Dr. John",
"followUpInstructions": "Instruction"
}

Referral

"data": {
"referredTo": "Cardiology Department",
"referralDate": "2025-08-28T00..",
"referralNotes": "Note",
"referralReason": "Reason",
"referringPhysician": "Dr. John"
}

Mental Health

"data": {
"assessment": "Mild depression ",
"nextSession": "2025-08-22T00..",
"sessionNotes": "Note"
}

Progress Note

"data": {
"update": "Patient's current status",
"reviewDate": "2025-08-22T00.."
}

Consent Form

"data": {
"signedAt": "2025-08-22T00:00:..",
"signedBy": "Patient",
"procedure": "Blood transfusion",
"attachments": [
    {
    "fileUrl": "https://refnvkredfnlvfe",
    "fileName": "Attachment"
    }
]
}

Dental Record

"data": {
"notes": "Additional notes",
"procedure": "Tooth extraction",
"performedAt": "2025-08-21T00.."
}

Eye Exam

"data": {
"result": "20/20 vision",
"examinedAt": "2025-08-23T00..",
"recommendation": "No lenses required"
}

Emergency Visit

"data": {
"reason": "Accident",
"arrivalTime": "2025-08-15T20..",
"treatmentGiven": "Treatment given"
}
GET /records/multiple/{healthId}
Retrieve all medical records for a patient from all sources.

Headers

Authorization: Bearer sk_test_1234567890abcdef x-consent-token: ct_1234567890abcdef

Query Parameters

Parameter Type Required Description
recordType string No Filter by record type (diagnosis, prescription, lab, note)
from string (ISO) No Start date filter
to string (ISO) No End date filter

Medicard Management

The Medicard API is a set of endpoints within the Healthstack infrastructure that enables healthcare businesses to issue, manage, and utilize digital health cards (Medicards) for patients. A Medicard acts as a secure digital identity and billing tool, allowing patients to access their medical records instantly and pay for healthcare services.
POST /medicard/create

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{
    "health_id": HID-PSE8RUOK,
    "cardName": Jane Doe,
    "cardType": Black Medicard,
}

Request Body Parameters

Parameter Type Required Description
health_id string Yes Unique patient identifier in format HID-XXXXXXXX
cardName string Yes Name to be displayed on the Medicard
cardType string Yes Type of Medicard to be created

Response

Response Body Parameters 
{
    "success": true,
    "status": true,
    "message": "Medicard created successfully",
    "data": [
        {
            "id": "454e23a2-4e56-4e9f-902c-6b38d59dadf6",
            "health_id": "HID-NHG869UP",
            "card_number": "MED-KMSII94S",
            "card_name": "Test card",
            "balance": 0,
            "business_id": "BUS-AFV2LA01",
            "created_at": "2025-07-22T11:58:58.058435+00:00",
            "updated_at": "2025-07-22T11:58:58.058435+00:00",
            "active": false,
            "card_type": "Black Medicard",
            "expires_at": "18/25",
            "card_pin": null,
            "failedAttempt": 5,
            "metadata": {
                "goal": [],
                "limit": 100000
            },
            "status": "assigned"
        }
    ],
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully created
status integer Indicates the status of the request
message string Descriptive message about the Medicard creation
data object Data of the request
PATCH /medicard/activate
Activate a Medicard with a PIN for the patient.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{ 
    "health_id": HID-PSE8RUOK,
    "card_pin": 4432,
    "card_number": MED-KMSII94S,
}

Request Body Parameters

Parameter Type Required Description
health_id string Yes Unique patient identifier in format HID-XXXXXXXX
card_pin number Yes 4-digit PIN for Medicard activation
card_number string Yes Unique card number for the Medicard

Response

Response Body Parameters 
{
    "status": true,
    "message": "Medicard activated successfully",
    "data": {
        "health_id": "HID-PSE8RUOK",
        "active": "true",
        "card_number": "MED-KMSII94S"
    },
    
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully activated
status integer Indicates the status of the request
message string Descriptive message about the Medicard activation
data object Data of the request
PATCH /medicard/deactivate
Deactivate a Medicard for the patient.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{ 
    "card_number": HID-PSE8RUOK,
    "reason": 4432,
}

Request Body Parameters

Parameter Type Required Description
card_number string Yes Unique card number for the Medicard
reason string Yes Reason for deactivating the Medicard

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard deactivated successfully",
    "data": {
        "health_id": "HID-IELEOR7G",
        "active": false,
        "card_number": "MED-B35ZF00M"
    }, 
}

Response Parameters

Parameter Type Description
status boolean Indicates whether the Medicard was successfully activated
message string Descriptive message about the Medicard activation
data.health_id string Patient's unique health identifier
data.medicard_status string Updated status of the Medicard (e.g., 'active', 'activated')
data.activated_at string Timestamp of Medicard activation in ISO format
POST /medicard/reserve
Reserve Medicards.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{ 
    "quantity": 2,
    "cardType": Black Medicard,
}

Request Body Parameters

Parameter Type Required Description
quantity number Yes Quantity of Medicards to reserve
cardType string Yes Type of Medicard to reserve

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "2 Medicards created successfully",
    "data": [], 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard reservation
data array Data of the request
POST /medicard/assign
Assign a Medicard to a patient.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{ 
    "health_id": HID-IELEOR7G,
    "cardName": Test Card,
    "cardType": Black Medicard,
    "cardNumber": MED-B35ZF00M,
    "expires_at": 2025-01-01,
}

Request Body Parameters

Parameter Type Required Description
health_id string Yes Unique patient identifier in format HID-XXXXXXXX
cardName string Yes Name displayed on the Medicard
cardType string Yes Type of Medicard to assign
cardNumber string Yes Unique card number for the Medicard
expires_at string Yes Expiration date of the Medicard

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard assigned successfully",
    "data": {
        "id": "2f55d6c1-c443-40fe-ba1b-d7ce077b9559",
        "health_id": "HID-E5CNO4UB",
        "card_number": "MED-9Y2OV2KT",
        "card_name": "Test card",
        "balance": 0,
        "business_id": "BUS-AFV2LA01",
        "created_at": "2025-07-22T13:08:00.71756+00:00",
        "updated_at": "2025-07-22T13:08:00.71756+00:00",
        "active": false,
        "card_type": "Black Medicard",
        "expires_at": "2025-01-01",
        "card_pin": null,
        "failedAttempt": 5,
        "metadata": {
            "goal": [],
            "limit": 100000
        },
        "status": "assigned"
    }, 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data object Data of the request
data.id string Unique identifier for the assigned Medicard
data.health_id string Unique patient identifier in format HID-XXXXXXXX
data.card_number string Unique card number for the Medicard
data.card_name string Name displayed on the Medicard
data.balance number Balance of the Medicard
data.business_id string Unique business identifier in format BUS-XXXXXXXX
data.created_at string Timestamp of Medicard creation in ISO format
data.updated_at string Timestamp of Medicard update in ISO format
data.active boolean Indicates if the Medicard is active
data.card_type string Type of Medicard
data.expires_at string Expiration date of the Medicard
data.card_pin string PIN of the Medicard
data.failedAttempt number Number of failed attempts to access the Medicard
data.metadata object Metadata of the Medicard
data.metadata.goal array Goal of the Medicard
data.metadata.limit number Limit of the Medicard
data.status string Status of the Medicard
GET /medicard/single/:card_number
Get a Medicard by card number.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard fetched successfully",
    "data": {
        "id": "2f55d6c1-c443-40fe-ba1b-d7ce077b9559",
        "health_id": "HID-E5CNO4UB",
        "card_number": "MED-9Y2OV2KT",
        "card_name": "Test card",
        "balance": 0,
        "business_id": "BUS-AFV2LA01",
        "created_at": "2025-07-22T13:08:00.71756+00:00",
        "updated_at": "2025-07-22T13:08:00.71756+00:00",
        "active": false,
        "card_type": "Black Medicard",
        "expires_at": "2025-01-01",
        "card_pin": null,
        "failedAttempt": 5,
        "metadata": {
            "goal": [],
            "limit": 100000
        },
        "status": "assigned"
    }, 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data object Data of the request
data.id string Unique identifier for the assigned Medicard
data.health_id string Unique patient identifier in format HID-XXXXXXXX
data.card_number string Unique card number for the Medicard
data.card_name string Name displayed on the Medicard
data.balance number Balance of the Medicard
data.business_id string Unique business identifier in format BUS-XXXXXXXX
data.created_at string Timestamp of Medicard creation in ISO format
data.updated_at string Timestamp of Medicard update in ISO format
data.active boolean Indicates if the Medicard is active
data.card_type string Type of Medicard
data.expires_at string Expiration date of the Medicard
data.card_pin string PIN of the Medicard
data.failedAttempt number Number of failed attempts to access the Medicard
data.metadata object Metadata of the Medicard
data.metadata.goal array Goal of the Medicard
data.metadata.limit number Limit of the Medicard
data.status string Status of the Medicard
GET /medicard/patients
Get all Medicards by a business.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard fetched successfully",
    "data": [{
        "id": "2f55d6c1-c443-40fe-ba1b-d7ce077b9559",
        "health_id": "HID-E5CNO4UB",
        "card_number": "MED-9Y2OV2KT",
        "card_name": "Test card",
        "balance": 0,
        "business_id": "BUS-AFV2LA01",
        "created_at": "2025-07-22T13:08:00.71756+00:00",
        "updated_at": "2025-07-22T13:08:00.71756+00:00",
        "active": false,
        "card_type": "Black Medicard",
        "expires_at": "2025-01-01",
        "card_pin": null,
        "failedAttempt": 5,
        "metadata": {
            "goal": [],
            "limit": 100000
        },
        "status": "assigned"
    },
    ...
    ], 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data array Data of the Medicards
data.id string Unique identifier for the assigned Medicard
data.health_id string Unique patient identifier in format HID-XXXXXXXX
data.card_number string Unique card number for the Medicard
data.card_name string Name displayed on the Medicard
data.balance number Balance of the Medicard
data.business_id string Unique business identifier in format BUS-XXXXXXXX
data.created_at string Timestamp of Medicard creation in ISO format
data.updated_at string Timestamp of Medicard update in ISO format
data.active boolean Indicates if the Medicard is active
data.card_type string Type of Medicard
data.expires_at string Expiration date of the Medicard
data.card_pin string PIN of the Medicard
data.failedAttempt number Number of failed attempts to access the Medicard
data.metadata object Metadata of the Medicard
data.metadata.goal array Goal of the Medicard
data.metadata.limit number Limit of the Medicard
data.status string Status of the Medicard
GET /medicard/reserved/:business_id
Get all reserved Medicards by a business.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard fetched successfully",
    "data": [{
        "id": "c7285713-b08c-442c-958f-74129fcde555",
        "card_number": "MED-RU9KPW1H",
        "business_id": "BUS-AFV2LA01",
        "created_at": "2025-07-14T16:53:23.911657+00:00",
        "active": false,
        "card_type": "Blue Medicard",
        "expires_at": "18/25",
        "metadata": {
            "goal": [],
            "limit": 100000
        },
        "status": "not_assigned"
    },
    ...
], 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data array Data of the Medicards
data.id string Unique identifier for the Medicard
data.card_number string Unique card number for the Medicard
data.business_id string Unique business identifier in format BUS-XXXXXXXX
data.created_at string Timestamp of Medicard creation in ISO format
data.active boolean Indicates if the Medicard is active
data.card_type string Type of Medicard
data.expires_at string Expiration date of the Medicard
data.metadata object Metadata of the Medicard
data.metadata.goal array Goal of the Medicard
data.metadata.limit number Limit of the Medicard
GET /medicard/transactions/:card_number
Get all transactions for a Medicard.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard transactions fetched successfully",
    "data": [{
        "id": 7,
        "created_at": "2025-07-15T08:01:46.905853+00:00",
        "card_number": "MED-B35ZF00M",
        "amount": 4000,
        "health_id": "HID-IELEOR7G",
        "metadata": {
            "receiver": "ST. Peters clinic"
        },
        "transaction_ref": "443153435534344",
        "type": "Consultations",
        "status": "pending",
        "business_id": "BUS-AFV2LA01"
    },
    ...
], 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data array Data of the Medicards
GET /medicard/business-transaction/:business_id
Get all transactions for a business.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard transactions fetched successfully",
    "data": [{
        "id": 7,
        "created_at": "2025-07-15T08:01:46.905853+00:00",
        "card_number": "MED-B35ZF00M",
        "amount": 4000,
        "health_id": "HID-IELEOR7G",
        "metadata": {
            "receiver": "ST. Peters clinic"
        },
        "transaction_ref": "443153435534344",
        "type": "Consultations",
        "status": "pending",
        "business_id": "BUS-AFV2LA01"
    },
    ...
], 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data array Data of the Medicards
POST /medicard/fund/:card_number
Fund a Medicard.

Headers

Authorization: Bearer sk_test_1234567890abcdef

Request Body

Request Body Parameters 
{  
    "card_number": MED-B35ZF00M,
    "reference": 1234567890,
    "amount": 4000,
}

Request Body Parameters

Parameter Type Required Description
card_number string Yes Unique card number for the Medicard
reference string Yes Reference for the transaction
amount number Yes Amount to fund the Medicard

Response

Response Body Parameters 
{
    "success": true,
    "status": 200,
    "message": "Medicard funded successfully",
    "data": {
        "reference": "1234567890",
        "amount": 4000,
        "card_number": "MED-B35ZF00M"
    }
, 
}

Response Parameters

Parameter Type Description
success boolean Indicates whether the Medicard was successfully reserved
status integer Indicates the status of the request
message string Descriptive message about the Medicard assignment
data object Data of the transaction
data.reference string Reference for the transaction
data.amount number Amount funded to the Medicard
data.card_number string Unique card number for the Medicard

KYC Tier Access Control

Tier 1

  • Hospitals
  • Clinics
  • Pharmacies
  • Diagnostic Centers
  • Homecare Agencies

Tier 2

  • Telemedicine Platforms
  • Digital Health Apps
  • Health Insurance Platforms
  • Virtual Clinics
  • Medical SaaS Providers

Security & Compliance

Data Integrity Rules

  • Immutable Records: Medical records cannot be deleted or updated once submitted
  • Timestamped: All records include creation timestamps
  • Source-Tagged: All records are tagged with the creating business
  • Audit Trail: Only HealthStack admin can audit submissions

Security Requirements

  • All communication must be over HTTPS
  • Consent tokens are temporary and patient-specific
  • Emergency access is logged and reviewed
  • All patient data access requires consent unless emergency access is granted

Error Handling

Error Code Description Solution
401 Unauthorized - Invalid or expired access token Refresh your access token
403 Forbidden - Insufficient KYC tier or missing consent Upgrade KYC tier or obtain consent token
404 Patient not found Create patient first or check HealthID
422 Validation error Check request body format and required fields