How-to guide
How to build on the pathology API, from staging to production
The path a healthtech takes to put pathology ordering and results inside its own product: a staging organisation, API credentials, the first request, the first referral, results by webhook, Medicare provider records, then the same setup in production.
Two environments, set up once each
Staging (app.staging.eirly.health, api.staging.eirly.health) and production (app.eirly.health, api.eirly.health) are separate: separate accounts, organisations, billing and credentials. Keys from one do not work in the other. Build and validate in staging, then repeat the setup in production when you are ready to order for real.
Step 1: credentials
Sign up and verify
Create an account in staging, complete verification and select a practitioner type (Other if none fits). Verification is required before an organisation can be created.
Create the organisation
All API access is scoped to an organisation: it owns the referrals, results, billing and credentials.
Billing method
A valid billing method must be on file before API access can be enabled. Staging accepts a Stripe test card and never charges a real card.
Enable the API
Settings, then API Keys. You receive a client_id and client_secret for that environment.
Step 2: the first request
Exchange the credentials for an access token with the client credentials flow, then call an endpoint with the token in the Authorization header. Listing tests is the usual first call.
GET https://api.staging.eirly.health/v1/tests
Authorization: Bearer YOUR_ACCESS_TOKENIllustrative sample, trimmed for this page. The full contract is in the Eirly Health docs.
Every list endpoint pages the same way, with a cursor. Point your coding assistant at the developer MCP server so it reads the reference while it writes your integration.
Step 3: the first referral
Choose the tests
List tests, or order a pre-configured set by bundle and extend it with extra tests. Commercial and Medicare tests can go in the same request.
Create the referral
POST /v1/referrals with the person and the tests. Eirly Health creates and issues the referral and you retrieve the referral PDF. An order with both Medicare and commercial tests produces two referrals.
Show the nearest centre
Collection-centre search returns centres by location, nearest first, with opening hours. The person walks in; most tests need no appointment.
Step 4: results by webhook
Create a webhook subscription over REST. Webhooks are notifications, not data: when a referral or a result is created or updated you receive a small event, and you fetch the current state from the REST API, which is the source of truth. Each biomarker has a consistent identity across labs and a canonical value beside the lab's own.
Event list and retry behaviour are in the webhooks reference; what a result looks like is on the lab results API page.
Step 5: Medicare provider records
Create the provider record
POST /v1/providers with the doctor's provider number, name, address and a PNG signature. The doctor needs no account with Eirly Health; that practitioner can order Medicare tests from this call on. Needs API version 1.1.0 or higher for Medicare referrals.
Request result routing
POST /v1/providers/{providerNumber}/routing, naming the labs from GET /v1/vendors. It records your attestation that you hold the doctor's written authority and queues one request per lab; it sends no email itself.
Labs confirm over time
Eirly Health notifies the labs in batches; each request moves to PENDING_CONFIRMATION, then CONNECTED when the lab confirms. Poll GET /v1/providers/{providerNumber} and read connections[].status.
Order meanwhile
Ordering works from the first call. Until a lab is CONNECTED its Medicare results do not route back automatically; every referral response says where it stands.
Step 6: go to production
Repeat steps 1 and 5 in production: new account, organisation, billing method, credentials and provider records. Production needs a plan; staging is free to build in. Then switch your base URL and keys.
Plans and what each includes: API pricing.
Eirly dev security: tips and tricks
No key in the browser, ever
A client_id and client_secret in an HTML page, a bundle or a mobile app is public. Exchange them for a token on your server, or at build time, and ship only data. The finder on this site is built that way.
Never commit a secret
Keep credentials in environment variables or your CI's encrypted secrets, add .env files to .gitignore, and scan commits before they leave your machine. If a secret reaches a repository, treat it as leaked: rotate it in Settings, then API Keys, and rewrite nothing.
One key per environment, one per job
Staging and production issue separate keys and neither works in the other. Give an integration its own organisation and key so you can revoke it without touching anything else.
Keep tokens out of logs
Access tokens last an hour and refresh tokens a month; log neither. Mask them in error reports and never put them in a URL.
Patients only in production
Staging is for made-up people. A real name, Medicare number or result never belongs in a test environment, a fixture, a screenshot or a bug report.
Verify what arrives
Treat a webhook as a notification, then fetch the record from the API with your token before you act on it. Reject anything your server did not ask for.
Least privilege for people too
In the app, roles add up and no built-in role grants Medicare ordering; give each person the capabilities their job needs and rotate API keys when someone who held them leaves.
Tell us
If you find a security problem in the API, the app or this site, email support@eirly.health with the detail and we will respond; please do not post it publicly first.
Frequently asked questions
Yes. Staging is a full environment with its own keys, and it never charges a real card. Production needs a plan.
No. A webhook tells you something changed; you fetch the referral or result from the REST API. Webhooks and list endpoints cover orders created through the API.
Not through the API: a provider record holds their number, details and signature. On the platform, each ordering doctor is a member with their own signature.
No. It is a REST API with OAuth 2.0 client credentials, cursor paging and JSON; the developer MCP server lets a coding assistant read the reference while it writes your client.
Your branding can appear on referrals, included or as an add-on depending on your plan.
Keep reading
- All how-to guides
Getting up and running, by type of organisation.
- Pathology API
Referrals, results, webhooks, bundles and collection centres in one REST API.
- Pathology booking API
Create the referral, find the nearest centre and get the result, in one API.
- Lab results API
Results normalised across labs, with canonical values and the lab's own report text.
Build on the Eirly Health API.
Start in the staging environment with its own keys. Production needs a plan, quoted to your volume.