Introduction

The Healthstack Developer API is a REST interface for managing patient identity, medical records, consent, and Medicard from your own apps and automations.

Developer API access requires an active Healthstack business account. Secret keys are generated in Settings → API Configuration. Use Test keys in sandbox and Live keys in production.

Base URL

All endpoints are served over HTTPS under /api/v1:

https://api.healthstackhq.com/api/v1

Authentication

Authenticate API requests using an API access token. Pass the token in the Authorization header as a Bearer token. Tokens typically start with sk_test_ (Test) or sk_live_ (Live).

Authorization: Bearer <your_api_token>

Authentication

Authenticate API requests using an API access token. Pass the token in the Authorization header as a Bearer token. Tokens typically start with sk_test_ (Test) or sk_live_ (Live).

Generate tokens in Settings → API Configuration. Use Test keys in sandbox and Live keys in production. Rotate or revoke a key anytime from the same page.

Secret key

Include your secret key on every request:

Authorization: Bearer <your_api_token>

Consent token

Patient-protected endpoints also require a short-lived consent token after the patient verifies an OTP:

x-consent-token: <consent_token>

Token reference

TokenPurposeValidityHeader
Secret Key API authentication Until rotated Authorization: Bearer
ConsentToken Patient data access 24 hours x-consent-token

Errors

The API uses conventional HTTP response codes and returns JSON error bodies.

Error response

{
  "status": false,
  "message": "Description of what went wrong",
  "error": "ERROR_CODE"
}

Common status codes

CodeMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid secret key
403Forbidden — missing consent or insufficient KYC tier
404Resource not found
429Rate limited
500Server error

Key Concepts

Core identifiers and access patterns used across the Healthstack API.

Core identifiers

Phone

Phone number is used to identify patients across healthcare systems.

Health ID

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

Access model

Secure authentication

Bearer secret keys plus consent tokens for protected patient data.

Consent management

Strict consent-based access control ensuring patient data privacy.

Tier-based access

KYC tiers control which businesses can access which capabilities.

POST

Create Patient

POST /patients/create

Create a new patient or fetch existing patient by thier phone number. This step is required before requesting consent.

Headers

Authorization: Bearer <your_api_token>

Request Body

Request Body Parameters 
{
    
    "name": Jane Doe,
    "gender": female,
    "dob": 1990-01-01,
    "phone": +2349011684637,
    "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)
dob string Yes Date of birth in ISO format (YYYY-MM-DD)
phone string Yes Phone number
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",
        "phone": "+2349011684637",
        "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.phone string Phone Number
data.email string Patient's email address
data.created_at string Timestamp of patient record creation in ISO format
POST

Seek Consent

POST /patients/seek-consent

Send verification code to patient's email or phone for consent.

Headers

Authorization: Bearer <your_api_token>

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

Verify Consent

POST /patients/consent

Verify OTP and receive consent token for patient data access.

Headers

Authorization: Bearer <your_api_token>

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

List Patients

GET /patients/multiple

Get all patients created by a business.

Headers

Authorization: Bearer <your_api_token>

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

Get Patient

GET /patient/single/:health_id

This endpoint is used to get user's record by user health id.

Note:Consent token is required to get a record for patients you did not create.

Headers

Authorization: Bearer <your_api_token>
x-consent-token: <consent_token>

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

Update Patient

PATCH /edit/:health_id

This endpoint is used to edit user's record by user health id.

Note:Consent token is required to get a record for patients you did not create.

Headers

Authorization: Bearer <your_api_token>
x-consent-token: <consent_token>

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
POST

Create Record

POST /records/create

Create a new medical record for a patient. Requires valid consent token for patients you did not create.

Headers

Authorization: Bearer <your_api_token> x-consent-token: <consent_token>

Request Body (form-data)

Parameter Description
recordType Prescription
patient HID-6TZM9Z8K
note Short note
record_files Medical record to upload (png,jpg,jpeg)
diagnosedBy Dr. Mike
diagnosed_at 2025-08-28T16:04:34.046+00:00
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

Prescription

Lab Results

Vital Signs

Consultation

Imaging

Surgery

Allergy

Vaccination

Admission

Discharge

Referral

Mental Health

Progress Note

Consent Form

Dental Record

Eye Exam

Emergency Visit

GET

List Records

GET /records/multiple/{healthId}

Retrieve all medical records for a patient from all sources.

Headers

Authorization: Bearer <your_api_token> x-consent-token: <consent_token>

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
GET

Records by Medicard

GET /records/{medicard_number}/{card_pin}

Retrieve all medical records for a patient with their Medicard number and card pin.

Headers

Authorization: Bearer <your_api_token> x-consent-token: <consent_token>

Query Parameters

Parameter Type Required Description
medicard_number string Yes Medicard number
card_pin string Yes Card pin
Response Body Parameters 
{
    "success": true, 
    "message": "Records fetched successfully",
    "data": {
            "records": [],
            "patient": "HID-NHG869UP", 
            "business_id": "BUS-6QWNSA9I"
    }
    
}
GET

Get Record

GET /records/single/{record_id}

Retrieve a single medical record for a patient with record id.

Headers

Authorization: Bearer <your_api_token> x-consent-token: <consent_token>

Query Parameters

Parameter Type Required Description
record_id string Yes Record id
Response Body Parameters 
{
    "success": true, 
    "message": "Records fetched successfully",
    "data": {
            "records": [], 
            ...other record details
    }
    
}
POST

Create Medicard

POST /medicard/create

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.

Headers

Authorization: Bearer <your_api_token>

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

Activate Medicard

PATCH /medicard/activate

Activate a Medicard with a PIN for the patient.

Headers

Authorization: Bearer <your_api_token>

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

Deactivate Medicard

PATCH /medicard/deactivate

Deactivate a Medicard for the patient.

Headers

Authorization: Bearer <your_api_token>

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

Reserve Medicard

POST /medicard/reserve

Reserve Medicards.

Headers

Authorization: Bearer <your_api_token>

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

Assign Medicard

POST /medicard/assign

Assign a Medicard to a patient.

Headers

Authorization: Bearer <your_api_token>

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

Get Medicard

GET /medicard/single/:card_number

Get a Medicard by card number.

Headers

Authorization: Bearer <your_api_token>

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 /medicard/patients

Get all Medicards by a business.

Headers

Authorization: Bearer <your_api_token>

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

List Reserved

GET /medicard/reserved/:business_id

Get all reserved Medicards by a business.

Headers

Authorization: Bearer <your_api_token>

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

Card Transactions

GET /medicard/transactions/:card_number

Get all transactions for a Medicard.

Headers

Authorization: Bearer <your_api_token>

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

Business Transactions

GET /medicard/business-transaction/:business_id

Get all transactions for a business.

Headers

Authorization: Bearer <your_api_token>

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

Fund Medicard

POST /medicard/fund/:card_number

Fund a Medicard.

Headers

Authorization: Bearer <your_api_token>

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

Consent Workflow

Standard Flow: Consent is always required to access a patient's protected medical data unless a valid Medicard or emergency parameter is present (Tier 3 businesses only).

1. Create/Fetch Patient

Use the patient's phone number to create a new patient profile or fetch an existing one.

POST /patients/create

2. Request Consent

Send a 6-digit verification code to the patient's phone or email linked to their HID.

POST /patients/seek-consent

3. Verify OTP

The patient enters the 6-digit verification code to generate a ConsentToken.

POST /patients/consent

4. Access Data

Use the ConsentToken to read or write the patient's medical records, prescriptions, or other sensitive data.

Include x-consent-token header

KYC Tiers

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