Introduction

The Healthstack Developer API is a REST interface for managing patient identity, medical records, consent, and Medicard from your own apps and automations. It's built for hospitals, clinics, pharmacies, telemedicine platforms, and other healthcare businesses integrating with Healthstack.

Developer API access requires an active Healthstack business account. Secret keys are generated in Settings → API Configuration. Use Test keys in sandbox (dummy data, no charges) and Live keys in production.

What you can build

Patients

Create and look up patients by phone number or Health ID, and run the consent flow that unlocks access to their data.

Create Patient →

Medical Records

Write diagnoses, prescriptions, lab results, and other record types, and retrieve a patient's full history from any source.

Create Record →

Medicard

Issue and manage digital health cards patients can use to access their records instantly and pay for healthcare services.

Create Medicard →

Base URL

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

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

Quick start

Most integrations follow the same core flow: create a patient, obtain their consent, then read or write their data.

1. Create a patient

Register the patient with their phone number, or fetch them if they already exist.

POST /patients/create

2. Request consent

Send a one-time verification code to the patient's phone or email.

POST /patients/seek-consent

3. Verify the OTP

Exchange the code the patient received for a short-lived consent token.

POST /patients/consent

4. Read or write data

Pass the consent token on protected endpoints to access the patient's records or Medicard.

x-consent-token: <consent_token>

See the full Consent Workflow guide for the end-to-end sequence, including when consent can be skipped.

Authentication

Every request is authenticated with a Bearer secret key in the Authorization header. Tokens start with sk_test_ (Test) or sk_live_ (Live). Patient-protected endpoints additionally require the consent token from the flow above.

Authorization: Bearer <your_api_token>

See the Authentication page for the full token reference.

Learn more

Key Concepts

Core identifiers and access patterns used across the API.

Read more →

KYC Tiers

Which capabilities are available to your business, based on its verification tier.

Read more →

Errors

Status codes and the error response format returned by the API.

Read more →

Security & Compliance

Data integrity rules and security requirements for handling patient data.

Read more →

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,


}

The Create Patient endpoint accepts a POST request, with name, gender, dob, phone, and email as required parameters.

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"
    },

}

This endpoint returns the following values status, message, and data containing health_id, name, phone, email, and created_at.

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,
}

The Seek Consent endpoint accepts a POST request, with health_id as the required parameter. A verification OTP is sent to the patient's registered phone number or email.

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",
}

This endpoint returns the following values success, status, and message.

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,
}

The Verify Consent endpoint accepts a POST request, with health_id and otp as required parameters.

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",
    },
}

This endpoint returns the following values success, status, message, and data containing consentToken and health_id.

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"
            }
        },
        ...
    ],
}

This endpoint returns the following values success, status, message, and data, an array of patient objects containing id, full_name, gender, dob, health_id, created_at, email, business_id, updated_at, and metadata.

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
    ],
}

This endpoint returns the following values success, status, message, and data containing the patient's id, full_name, gender, dob, health_id, created_at, email, business_id, updated_at, vital, and metadata.

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
            }
       ,
    },
}

This endpoint returns the following values success, status, message, and data containing the updated metadata.

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>

The Create Record endpoint accepts a POST request as multipart/form-data, with recordType, patient, note, record_files, diagnosedBy, and diagnosed_at as parameters.

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

This endpoint returns the following values success, status, message, and data containing recordId, patient, and created_at.

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>

The List Records endpoint accepts a GET request, with optional recordType, from, and to query parameters to filter results.

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>

The Records by Medicard endpoint accepts a GET request, with medicard_number and card_pin as required path parameters.

Query Parameters

Parameter Type Required Description
medicard_number string Yes Medicard number
card_pin string Yes Card pin

This endpoint returns the following values success, message, and data containing records, patient, and business_id.

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>

The Get Record endpoint accepts a GET request, with record_id as the required path parameter.

Query Parameters

Parameter Type Required Description
record_id string Yes Record id

This endpoint returns the following values success, message, and data containing the record details.

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,
}

The Create Medicard endpoint accepts a POST request, with health_id, cardName, and cardType as required parameters.

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"
        }
    ],
}

This endpoint returns the following values success, status, message, and data containing the created Medicard's details.

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,
}

The Activate Medicard endpoint accepts a PATCH request, with health_id, card_pin, and card_number as required parameters.

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"
    },

}

This endpoint returns the following values status, message, and data containing health_id, active, and card_number.

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,
}

The Deactivate Medicard endpoint accepts a PATCH request, with card_number and reason as required parameters.

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"
    },
}

This endpoint returns the following values success, status, message, and data containing health_id, active, and card_number.

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,
}

The Reserve Medicard endpoint accepts a POST request, with quantity and cardType as required parameters.

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": [],
}

This endpoint returns the following values success, status, message, and 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,
}

The Assign Medicard endpoint accepts a POST request, with health_id, cardName, cardType, cardNumber, and expires_at as required parameters.

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"
    },
}

This endpoint returns the following values success, status, message, and data containing the assigned Medicard's full details.

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"
    },
}

This endpoint returns the following values success, status, message, and data containing the Medicard's full details.

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"
    },
    ...
    ],
}

This endpoint returns the following values success, status, message, and data, an array of Medicards belonging to the business.

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"
    },
    ...
],
}

This endpoint returns the following values success, status, message, and data, an array of reserved Medicards.

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"
    },
    ...
],
}

This endpoint returns the following values success, status, message, and data, an array of transactions for the Medicard.

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"
    },
    ...
],
}

This endpoint returns the following values success, status, message, and data, an array of transactions for the business.

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,
}

The Fund Medicard endpoint accepts a POST request, with card_number, reference, and amount as required parameters.

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"
    }
,
}

This endpoint returns the following values success, status, message, and data containing reference, amount, and card_number.

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

Contact Help

Reach out to the Healthstack team for help with integration, billing, or anything else. We do our best to respond within 1 business day.

Get in touch

If you have any questions regarding our Services or need help, please fill out the form here. We do our best to respond within 1 business day.

Email

support@healthstackhq.com

Phone

+234 916 778 1306

Address

2 Gentle Street, Gbalaja, Port Harcourt, Nigeria