A complete reference for integrating with the Poveon laboratory request platform. All endpoints follow REST conventions and return JSON (unless noted).
https://poveon.comHTTPS onlyJSON / FormDataCookie / API KeyThe Poveon API enables healthcare systems and LIMS to automate lab request management. You can create requests programmatically, track their lifecycle, deliver results, and manage laboratory accounts — all through a clean REST interface.
Request Creation
Doctors or integrated systems submit patient test requests without a login.
Real-time Status
Poll or webhook-trigger status checks as patients progress through the lab.
Result Delivery
Attach PDF results or share secure links directly to doctors and patients.
Lab Management
Admin APIs let you provision and manage multiple lab accounts.
The API supports three access levels. Lab endpoints accept either a session cookie (for human users logging in via the portal) or an X-Poveon-Api-Key header (for LIMS and server integrations). Public endpoints require no credentials.
For machine-to-machine integrations, generate an API key from the Admin Dashboard → Labs → Dev panel. Pass it in every request as a header. Keys are hashed server-side — the raw value is only shown once at generation time.
# All lab endpoints accept this header instead of a session cookie: X-Poveon-Api-Key: pvn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
// Node.js example
const res = await fetch("https://poveon.com/api/requests/retrieve", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Poveon-Api-Key": process.env.POVEON_API_KEY,
},
body: JSON.stringify({ code: "CDL-A3X9B1" }),
});No authentication required. Any client can call these endpoints.
/api/labs/api/requests/createPass either a session cookie (portal login) or an X-Poveon-Api-Key header. Both grant the same access scoped to your lab.
/api/lab/requests/api/requests/retrieve/api/requests/update-status/api/requests/send-resultsRequires a Supabase session for a verified AdminUser record. Only Poveon staff accounts qualify.
/api/admin/*By default, all system emails — order confirmations, patient tracking codes, and result deliveries — are sent from Poveon's address (notifications@poveon.com). Labs can optionally have these emails sent from their own address instead.
When a lab has a notification_email configured (e.g. no-reply@apexdiagnostics.com), every email in the flow — including LIMS-triggered results — goes out from that address under the lab's name. Recipients see the lab's brand, not Poveon's.
Order confirmation
Sent to doctor when a request is created
Patient tracking code
Sent to patient if email was provided at creation
Patient arrived notice
Sent to doctor when lab retrieves the order
Results delivery
Sent to doctor and patient when lab sends results
Custom lab email addresses must be verified in Resend before they can be used. This is a one-time setup done by the Poveon team — labs cannot self-serve this step. Contact support@poveon.com with your desired sending address to get onboarded.
From Address — Before vs. After
Default (no custom email set)
From: Poveon <notifications@poveon.com>
With custom email configured
From: Apex Diagnostics <no-reply@apexdiagnostics.com>
Every lab request moves through three stages. Transitions are strictly enforced server-side.
| Transition | Trigger |
|---|---|
incoming → seen | Lab retrieves request by code |
seen → done | Lab updates status or sends results |
These are the entities your LIMS reads and updates over the API. The Request object is the core record.
Lab — returned by GET /api/labs
| Field | Type | Description |
|---|---|---|
| id | string (uuid) | Lab identifier (use as lab_id when creating requests). |
| name | string | Laboratory display name. |
| slug | string | null | URL slug for the lab's branded page. |
| address | string | null | Primary address. |
| phones | {number,label}[] | Contact numbers. |
| string | null | WhatsApp number (E.164). | |
| service_categories | string[] | Test categories the lab offers. |
| branches | LabBranch[] | Physical branches (name, address, phones). |
Price list entry — the lab's test catalog
| Field | Type | Description |
|---|---|---|
| id | string (uuid) | Catalog entry id. |
| raw_name | string | Test name as the lab provides it. |
| category_label | string | null | Category grouping. |
| synonyms | string[] | Alternate names used to match free-text requests. |
| lab_price | decimal (₦) | Patient-facing price for the test. |
Request — the central record
| Field | Type | Description |
|---|---|---|
| id | string (uuid) | Internal request identifier. |
| code | string | Unique, shareable code (e.g. LABA-8X4K29Q). Patient presents this at the lab. |
| lab_id | string | The lab this request belongs to. |
| status | enum | incoming | seen | done. |
| doctor_email | string | null | NULL = self-service patient; set = doctor-referred. |
| doctor_name | string | null | Referring doctor's name. |
| patient_name | string | null | Patient's full name. |
| patient_phone | string | null | E.164 phone, e.g. +2348001234567. |
| patient_email | string | null | Used for result delivery and portal auto-fill. |
| tests | string | Requested tests (comma-separated / free text). |
| condition | string | null | Symptoms or clinical note. |
| schedule | string | null | Requested appointment time. |
| test_image_url | string | null | Uploaded request slip / image. |
| result_link | string | null | External results URL (set when done). |
| result_note | string | null | Free-text result summary. |
| result_file_urls | string[] | Attached result PDFs / images. |
| poveon_amount | decimal | null | Poveon commission for this request (computed at 'seen'). |
| lab_revenue_amount | decimal | null | Lab's revenue after commission. |
| created_at | datetime | When the request was created. |
| seen_at | datetime | null | Set when status → seen. |
| completed_at | datetime | null | Set when status → done. |
incoming
Created; patient not yet at the lab.
seen
Patient arrived / acknowledged. Commission computed.
done
Tests complete; results attached & delivered.
All error responses include a JSON body with success: false and an error message string. Always check success before using the response data.
OK
Request succeeded
Bad Request
Validation failed or invalid input
Unauthorized
No valid session cookie or X-Poveon-Api-Key header present, or key is expired/revoked
Forbidden
Authenticated but insufficient permissions (e.g. member role lacks the required permission)
Not Found
Resource does not exist
Too Many Requests
Rate limit exceeded (e.g. 20 requests per doctor email per hour on /api/requests/create)
Server Error
Unexpected internal error
Error Response Format
{
"success": false,
"error": "Validation failed: patient_name is required"
}Some endpoints enforce hard rate limits. The limits below are actively enforced — requests that exceed them receive a 429 response.
20 requests per doctor email per hour
Enforced server-side. Returns 429 when exceeded. Resets on a rolling 1-hour window.
Poll at most once every 30 seconds
Not enforced but please follow this guideline. Continuous polling may be throttled.
Max 5 files · 10 MB each (results) / 5 MB (logos)
Enforced server-side. Returns 400 for oversized or too many files.
If your integration requires higher throughput, contact us at support@poveon.com.
🚀
Contact the Poveon team to get API credentials and onboard your LIMS or healthcare system.
Get in touch