MediQR Partner API
The MediQR API allows authorized HMOs and partners to connect their systems to MediQR — enabling hospital validation, card verification, online checkout validation, and claims management through a secure, per-client API key.
https://portal.mediqr.ng/api/v1Overview
Per-Client API Keys
Each HMO or Partner has its own unique API credentials. Keys are isolated — one client cannot access another's data.
Bearer Authentication
All API requests must include your API key as a Bearer token in the Authorization header.
Real Backend
Every endpoint connects to the live MediQR database. No mock data — responses reflect actual card and subscription state.
Hospital PIN Access
Hospitals connect via a PIN provided by their HMO. The PIN grants direct access to the MediQR hospital validation portal.
Checkout Validation
Partners can validate MediQR cards at online checkout for telemedicine and healthcare services. Usage is deducted automatically.
HMO-Side Validation
HMOs can validate cards from their own system and associate the transaction with the correct hospital.
Base URL
https://portal.mediqr.ng/api/v1
Authentication
All MediQR API endpoints require authentication using your API key as a Bearer token. Include the key in the Authorization header of every request.
GET /api/v1/validate?qr_reference=MDQR12345678 HTTP/1.1 Host: portal.mediqr.ng Authorization: Bearer YOUR_API_KEY Content-Type: application/json
HMO API Keys
HMO users: log in to your HMO dashboard and navigate to API & Developer Access. Generate a key from there.
Partner API Keys
Partner users: contact your MediQR administrator to have a Partner API key provisioned for checkout validation.
Key security
The full key is only shown once at generation. Store it securely in your environment variables.
Key revocation
If a key is compromised, revoke it immediately from your dashboard and generate a new one.
API Key Management
API keys are managed from your dashboard under API & Developer Access. Each client has exactly one active key at a time. Regenerating a key immediately revokes the previous one.
| Action | How | Effect |
|---|---|---|
| Generate (HMO) | Click "Generate API Key" in HMO dashboard → API & Developer Access | Creates a new active key. Full key shown once only. |
| Generate (Partner) | Contact MediQR administrator to provision a Partner API key | Creates a new active Partner key for checkout validation. |
| Regenerate | Click "Regenerate" in dashboard | Revokes existing key, creates new one immediately. |
| Revoke | Click "Revoke Key" in dashboard | Immediately invalidates the key. All API calls using it return 401. |
| View status | API & Developer Access section | Shows key prefix, creation date, last used date, and status. |
Hospital PIN Authentication
MediQR SmartCover Validation for Hospitals
When an HMO connects MediQR to its hospital system, each hospital receives a unique Hospital Access PIN. Hospital staff use this PIN to access the MediQR Hospital Validation Portal directly — without needing a separate MediQR login account.
How Hospital PIN Access Works
HMO adds hospital
The HMO creates the hospital in their MediQR dashboard. A unique Hospital Access PIN is automatically generated and sent to the hospital.
Hospital accesses the portal
In the hospital's system, staff click the "MediQR SmartCover Validation" option, which opens the MediQR Hospital Validation Portal at /hospital.
Hospital enters PIN
The hospital enters its Hospital Access PIN. The system identifies the hospital through the HMO/API relationship and grants access.
Full validation workflow
Once authenticated, the hospital has access to: Scan QR, Validate by card/QR or phone number, Capture first-time patients, View card status and validity, Record visits, File claims.
Hospital PIN Notice
Hospital Access PINs are provided by the HMO. If a hospital does not have its PIN, it should contact its HMO. If the HMO does not have the PIN, contact the MediQR administrator.
Hospital Portal URL
https://portal.mediqr.ng/hospital
This URL can be embedded in the hospital's system as the "MediQR SmartCover Validation" link. The hospital enters its PIN on this page to access the full validation workflow.
API Endpoints
Quickly validate a card or QR code by its MDQR reference number. Returns the card's current status, validity, and usage information. Use this for fast point-of-care validation.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| qr_reference | string (query) | Required | The MDQR number or card reference (e.g. MDQR12345678) |
Request Example
curl -X GET \ "https://portal.mediqr.ng/api/v1/validate?qr_reference=MDQR12345678" \ -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
"success": true,
"data": {
"qr_reference": "MDQR12345678",
"card_status": "Active",
"is_valid": true,
"card_type": "Monthly",
"subscriber_name": "John Doe",
"subscriber_phone": "08012345678",
"activation_date": "2026-08-01T00:00:00Z",
"expiry_date": "2026-08-31T23:59:59Z",
"usage_count": 2,
"max_uses": 6,
"visits_remaining": 4
}
}Error Responses
Retrieve full card details including subscriber information, validity dates, and usage statistics for a specific MDQR card reference.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| reference | string (path) | Required | The MDQR number or card reference in the URL path |
Request Example
curl -X GET \ "https://portal.mediqr.ng/api/v1/card/MDQR12345678" \ -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
"success": true,
"data": {
"qr_reference": "MDQR12345678",
"card_status": "Active",
"is_valid": true,
"card_type": "Monthly",
"subscriber": {
"name": "John Doe",
"phone": "08012345678",
"gender": "Male",
"age_range": "30-39"
},
"validity": {
"activation_date": "2026-08-01T00:00:00Z",
"expiry_date": "2026-08-31T23:59:59Z"
},
"usage": {
"usage_count": 2,
"max_uses": 6,
"visits_remaining": 4
},
"subscription_id": "SUB-XXXXXXXX"
}
}Error Responses
Returns all hospitals assigned to the authenticated HMO. Use this to populate a hospital selector when performing HMO-side validation. Supports optional search by name or hospital code.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| search | string (query) | Optional | Optional search term to filter by hospital name or code |
Request Example
curl -X GET \ "https://portal.mediqr.ng/api/v1/hmo/hospitals?search=Lagos" \ -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
"success": true,
"data": [
{
"id": "uuid-here",
"name": "Lagos General Hospital",
"hospital_code": "HSP-ABC123",
"state": "Lagos",
"city": "Ikeja"
}
]
}Error Responses
HMO-Side Card Validation
The HMO can validate a MediQR card from its own system. The HMO submits the card/QR number, patient name, and the hospital where the service is being provided. The system verifies the card, confirms the hospital belongs to the HMO, and creates a pending transaction on the hospital's dashboard for treatment entry and claims filing.
Validation → Treatment Flow
Validate a MediQR card on behalf of a hospital. The HMO submits the card reference, patient name, and hospital. If the card is active and the hospital belongs to the HMO, a pending treatment record is created on the hospital's dashboard. The hospital can then open the transaction, enter treatment details, and file the claim.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| qr_reference | string (body) | Required | The MDQR number or card reference to validate |
| first_name | string (body) | Optional | Patient first name (optional) |
| last_name | string (body) | Optional | Patient last name (optional) |
| hospital_code | string (body) | Optional | Hospital code (use this OR hospital_id) |
| hospital_id | string (body) | Optional | Hospital UUID (use this OR hospital_code). One of hospital_code or hospital_id is required. |
Request Example
curl -X POST \
"https://portal.mediqr.ng/api/v1/hmo/validate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"qr_reference": "MDQR12345678",
"first_name": "John",
"last_name": "Doe",
"hospital_code": "HSP-ABC123"
}'Response Example
{
"success": true,
"data": {
"transaction_id": "uuid-of-treatment-record",
"qr_reference": "MDQR12345678",
"card_status": "Active",
"is_valid": true,
"patient_name": "John Doe",
"hospital": {
"id": "uuid-here",
"name": "Lagos General Hospital",
"hospital_code": "HSP-ABC123"
},
"card_type": "Monthly",
"subscriber_name": "John Doe",
"subscriber_phone": "08012345678",
"activation_date": "2026-08-01T00:00:00Z",
"expiry_date": "2026-08-31T23:59:59Z",
"usage_count": 2,
"max_uses": 6,
"visits_remaining": 4,
"message": "Validation successful. Transaction has been sent to the hospital dashboard for treatment entry."
}
}Error Responses
Validate Card Expiry
Use this endpoint to check whether a card is currently within its active coverage period. It returns the expiry status, days remaining, and whether coverage is currently active — without creating a treatment transaction. Useful for pre-checks before initiating a full validation.
Expiry Status Values
Card is within coverage period
Expires within 7 days
Coverage period has ended
No expiry date configured
Check whether a card is currently within its active coverage period. Returns expiry status, days remaining, activation and expiry dates, and whether coverage is currently active. Does not create a treatment transaction.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| qr_reference | string (query) | Required | The MDQR number or card reference to check (e.g. MDQR12345678) |
Request Example
curl -X GET \ "https://portal.mediqr.ng/api/v1/card-expiry?qr_reference=MDQR12345678" \ -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
"success": true,
"data": {
"qr_reference": "MDQR12345678",
"card_status": "active",
"expiry_status": "active",
"is_coverage_active": true,
"is_expired": false,
"days_remaining": 14,
"activation_date": "2026-08-01T00:00:00Z",
"expiry_date": "2026-08-31T23:59:59Z",
"subscriber_name": "John Doe",
"subscriber_phone": "08012345678"
}
}
// Expired card example:
{
"success": true,
"data": {
"qr_reference": "MDQR99887766",
"card_status": "expired",
"expiry_status": "expired",
"is_coverage_active": false,
"is_expired": true,
"days_remaining": 0,
"activation_date": "2026-07-01T00:00:00Z",
"expiry_date": "2026-07-31T23:59:59Z",
"subscriber_name": "Jane Smith",
"subscriber_phone": "08098765432"
}
}Error Responses
MediQR Checkout Validation API
MediQR Checkout Validation — For Approved Partners
This API allows an approved MediQR Partner to add a "Pay / Validate with MediQR" or "Continue with MediQR / SmartCover" option on their website or online healthcare / telemedicine checkout. It is not a payment gateway and does not process money. It validates whether a customer's MediQR card is eligible for the online service and deducts one usage from their subscription.
How It Works
Customer selects MediQR at checkout
On the partner's website or telemedicine platform, the customer selects "Pay with MediQR" or "Continue with MediQR / SmartCover".
Customer enters their MDQR number
The partner's website prompts the customer to enter their MediQR Card Number / MDQR Number / Voucher Number (format: MDQR12345678).
Partner calls the Checkout Validation API
The partner's backend sends the MDQR number to the MediQR Checkout Validation API with the partner's API key.
MediQR validates the card
The API checks: card exists, is valid, subscription is active, coverage has not expired, and remaining visits > 0.
Usage is deducted on success
If valid, 1 visit is deducted from the subscription. The remaining visits are returned in the response.
Partner allows or rejects the service
Based on the API response, the partner's platform allows the customer to proceed with the online consultation or rejects the request with the reason.
MDQR Number Format
The MediQR card number follows a short, easy-to-enter format with no dashes or spaces:
MDQR + 7 or 8 digits Examples: MDQR1234567 or MDQR12345678
Partner API Key Required
The Checkout Validation API requires a Partner API Key — not an HMO API key. Contact your MediQR administrator to have a Partner API key provisioned for your platform. Each approved partner has their own unique key. One partner cannot use another partner's key.
Usage / Visit Deduction Behaviour
| Scenario | Behaviour |
|---|---|
| Monthly Plan (e.g. 4 visits/month) | 1 visit deducted on successful validation. Remaining visits returned in response. |
| Daily Voucher (unlimited or 1 visit) | Usage recorded. If max_uses is set, 1 visit deducted. |
| Plan with no usage limit (max_uses = null) | Validation succeeds. No usage deducted. visits_remaining = null. |
| Card with 0 remaining visits | Validation fails with NO_USAGE_REMAINING error. No usage deducted. |
| Expired card | Validation fails with CARD_NOT_ACTIVE error. |
| Invalid / non-existent MDQR number | Validation fails with CARD_NOT_FOUND error. |
| Dry-run check (deduct_usage: false) | Validates eligibility without deducting usage. Useful for pre-checks. |
Validate a customer's MediQR card/voucher at online checkout. Checks card existence, validity, subscription status, expiry, and remaining usage. On success, deducts 1 visit from the subscription (where applicable) and returns the updated remaining visits. All checkout activity is recorded for admin reporting.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| mdqr_number | string (body) | Required | The customer's MediQR Card Number / MDQR Number / Voucher Number (e.g. MDQR12345678). Also accepted as card_number or qr_reference. |
| service_type | string (body) | Optional | Type of online service being accessed (e.g. "telemedicine", "consultation", "online_consultation"). Defaults to "online_consultation". |
| deduct_usage | boolean (body) | Optional | Whether to deduct 1 visit on successful validation. Default: true. Set to false for a dry-run eligibility check without deducting. |
Request Example
curl -X POST \
"https://portal.mediqr.ng/api/v1/partner/checkout-validate" \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mdqr_number": "MDQR12345678",
"service_type": "telemedicine"
}'Response Example
// Successful validation (with usage deducted):
{
"success": true,
"data": {
"mdqr_number": "MDQR12345678",
"card_status": "Active",
"is_eligible": true,
"subscriber_name": "John Doe",
"subscriber_phone": "08012345678",
"plan_type": "Monthly",
"plan_id": "uuid-of-plan",
"activation_date": "2026-08-01T00:00:00Z",
"expiry_date": "2026-08-31T23:59:59Z",
"usage_count": 3,
"max_uses": 4,
"visits_remaining": 1,
"usage_deducted": true,
"service_type": "telemedicine",
"message": "Validation successful. 1 visit deducted. Remaining visits: 1."
}
}
// Failed — card expired:
{
"success": false,
"error": {
"code": "CARD_NOT_ACTIVE",
"message": "Card is not eligible for online service. Status: Expired"
},
"data": {
"mdqr_number": "MDQR99887766",
"card_status": "Expired",
"is_eligible": false,
"activation_date": "2026-07-01T00:00:00Z",
"expiry_date": "2026-07-31T23:59:59Z"
}
}
// Failed — no remaining visits:
{
"success": false,
"error": {
"code": "NO_USAGE_REMAINING",
"message": "No remaining eligible visits/usage for this subscription."
},
"data": {
"mdqr_number": "MDQR11223344",
"card_status": "Active",
"is_eligible": false,
"visits_remaining": 0,
"max_uses": 4,
"usage_count": 4
}
}Error Responses
Integration Guide for Partner Technical Teams
Step 1: Get your Partner API Key
Contact your MediQR administrator to have a Partner API key provisioned. Store it securely as an environment variable on your server — never expose it in client-side code.
Step 2: Add MediQR to your checkout
Add a "Pay with MediQR" or "Continue with MediQR / SmartCover" button to your checkout page. When selected, show an input field for the customer's MDQR number.
Step 3: Call the API from your backend
Send the MDQR number to /api/v1/partner/checkout-validate from your server-side code. Never call this API from the browser — your API key must remain server-side.
Step 4: Handle the response
If success: true, allow the customer to proceed. If success: false, show the error message to the customer (e.g. "Card expired", "No remaining visits").
Step 5: Record the transaction
The MediQR system automatically records the checkout usage. You do not need to make a separate call to record it. The usage is reflected in the MediQR admin dashboard.
Dry-run pre-check (optional)
To check eligibility without deducting usage (e.g. before showing a confirmation screen), send deduct_usage: false. Then call again with deduct_usage: true when the customer confirms.
Claims Workflow
When an HMO validates a card via the API, a transaction record is created on the hospital's dashboard with status hmo_validated. The hospital opens the transaction, enters the treatment details, and submits the claim. The HMO can then view the resulting claim in its dashboard.
Hospital Dashboard
Hospitals see HMO-validated transactions in their Today's Patients and Treatment History. They open the transaction, enter treatment type, coverage, and notes, then submit the claim.
HMO Claims View
HMOs see all claims from their assigned hospitals in the Claims tab of their dashboard. Claims can be filtered by hospital, status, and searched by patient or QR reference.
Claim Statuses
hmo_validated → submitted → approved / rejected. The hospital moves the claim from hmo_validated to submitted when they file it.
Data Isolation
HMOs only see claims from their own hospitals. Hospital A's claims are never visible to HMO B.
Claim Status Values
| Status | Meaning | Next Action |
|---|---|---|
| hmo_validated | HMO validated the card via API. Awaiting hospital treatment entry. | Hospital enters treatment and submits claim. |
| submitted | Hospital has submitted the treatment record and claim. | HMO reviews and approves or rejects. |
| approved | HMO has approved the claim. | Claim is settled. |
| rejected | HMO has rejected the claim. | Hospital may resubmit with corrections. |
Error Reference
All error responses follow a consistent format with a machine-readable code and human-readable message.
{
"success": false,
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is not valid."
}
}| HTTP Status | Error Code | Description |
|---|---|---|
| 401 | MISSING_API_KEY | Authorization header is missing or does not start with "Bearer " |
| 401 | INVALID_API_KEY | The API key does not exist in the system |
| 401 | REVOKED_API_KEY | The API key has been revoked. Generate a new key from your dashboard. |
| 400 | MISSING_PARAMETER | A required query parameter, path parameter, or body field is missing |
| 404 | CARD_NOT_FOUND | No card or QR code found with the provided reference |
| 404 | HOSPITAL_NOT_FOUND | Hospital not found or does not belong to the authenticated HMO |
| 403 | HOSPITAL_INACTIVE | The specified hospital is currently inactive |
| 422 | CARD_NOT_ACTIVE | Card is not eligible for treatment (expired, used up, cancelled, unassigned, etc.) |
| 422 | NO_USAGE_REMAINING | Card is active but has no remaining eligible visits for this subscription (Checkout API only) |
| 403 | FORBIDDEN | The authenticated client is not authorized to access this resource |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests from this IP or API key. Please slow down. |
| 500 | SERVER_ERROR | An unexpected server error occurred. Contact support if this persists. |
Data Isolation & Security
Client-Level Data Isolation
Each API key is bound to a single HMO or Partner. An API key from one client cannot be used to access another client's data, hospitals, or claims. All requests are validated against the client associated with the API key.
Key Binding
Every API key is cryptographically bound to a specific HMO or Partner ID at generation time.
RLS Enforcement
Database Row Level Security policies enforce data boundaries at the database layer, not just application layer.
Hospital Verification
When validating via HMO API, the system verifies the specified hospital belongs to the authenticated HMO before proceeding.
Partner Isolation
Checkout validation logs are scoped to the partner. One partner cannot see another partner's checkout activity.
Usage Tracking
Every API call updates the last_used_at timestamp on the key for audit purposes.
Revocation
Revoked keys are immediately rejected. There is no grace period after revocation.
MediQR API Documentation · v1 · 2026