EirlyEirly
PartnersEirly APIPractitionersCatalogueAboutPricing
Sign inGet started

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.

Test it in stagingRead the docs

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.

First request (staging)
GET https://api.staging.eirly.health/v1/tests
Authorization: Bearer YOUR_ACCESS_TOKEN

Illustrative 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.

Test it in stagingRead the docs

EirlyEirly

Pathology and diagnostic infrastructure for practitioners and health brands.

Solutions

  • Partners
  • Telehealth services
  • Health brands and white label
  • Clinics and practitioners
  • Longevity clinics
  • Clinical trials
  • Research
  • At-home collection

Platform

  • Pathology infrastructure
  • Eirly API
  • Medicare pathology
  • Catalogue
  • How-to guides
  • Who can order tests
  • Pricing
  • API pricing

Developers

  • Pathology API
  • Lab results API
  • Pathology booking API
  • Lab testing API
  • Radiology API
  • MCP server
  • Guides

Company

  • About
  • Blog
  • Compliance
  • Contact

Legal

  • Privacy
  • Terms
  • Refunds

Our network

  • Pathology labs
  • Collection centres
  • Healius Pathology
  • Australian Clinical Labs
  • 4Cyte Pathology
  • Sonic Healthcare
  • NutriPATH
  • Microba
  • Fatty Acid Labs

Built in Australia. Global by design, local where it counts.

Eirly Health is a trading name of Bloody Good Tests Pty Ltd. Eirly provides data infrastructure and educational context. It does not provide medical advice, diagnosis or treatment. Pathology is requested by a registered practitioner and analysed by accredited or otherwise appropriately qualified laboratories. Practitioners using the platform are responsible for their own clinical and regulatory obligations.

© 2026 Bloody Good Tests Pty Ltd

Clients: sign in to view your results →