Hera Testing API (sandbox)

The API for labs that don't have APIs. Most labs that run a semen analysis take orders by fax, by e-sign or on their own paper form, and book by phone. Hera does that work: a physician signs the order, Hera gets it to the lab by whatever route the lab takes, confirms the lab has it, chases the result, and reads it back as structured data with an analysis. You call one API, from your backend or from your agent.

Phase 1 is a sandbox: invented labs and results, every stage and webhook, nothing real sent. Live ordering opens to design partners next. Email [email protected] for a sandbox key.

Quickstart

export HERA=hera_sk_test_…
curl -s "https://herafertility.co/api/v1/labs?zip=78701" -H "Authorization: Bearer $HERA"
curl -s https://herafertility.co/api/v1/patients -H "Authorization: Bearer $HERA" -H 'Content-Type: application/json' \
  -d '{"firstName":"Alex","lastName":"Sample","dob":"1990-01-01","email":"[email protected]"}'
curl -s https://herafertility.co/api/v1/orders -H "Authorization: Bearer $HERA" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-order-1' -d '{"patientId":"pat_…","labId":"lab_sbx_fax","test":"semen_analysis"}'
curl -s https://herafertility.co/api/v1/orders/ord_…/simulate -H "Authorization: Bearer $HERA" -H 'Content-Type: application/json' \
  -d '{"to":"result_received"}'
curl -s https://herafertility.co/api/v1/orders/ord_…/results -H "Authorization: Bearer $HERA"

Use it from an agent (MCP)

Add a remote MCP server (streamable HTTP) at https://herafertility.co/api/v1/mcp with the header Authorization: Bearer hera_sk_test_…. The tools are the same as the REST endpoints.

ToolWhat it does
labs_searchLabs near a US ZIP that take a Hera order for the test, with the lab price, where it is paid, Hera's order fee and how Hera reaches the lab (orderRoute). Use a lab id from here in orders_create.
patients_createCreates a patient for your organisation. In the sandbox, use invented details only: an example.com email and, if any, a 555-0100..0199 phone.
patients_getOne of your patients by id.
orders_createOrders a test for a patient at a lab. physician "hera" = a Hera physician signs the order; "own" = your physician's order is attached. Pass requestId so a retry returns the same order instead of making a second one.
orders_getOne order with its journey: the stage, since when, the next step, who owns it and when it is due, and the history.
orders_listYour most recent orders.
orders_cancelCancels an order that has not been to the lab yet.
orders_simulateSandbox only: moves an order forward to a stage, firing each stage's webhook in order (document_ready → delivered_to_lab → appointment_booked → visited → result_received). to "stalled" fires order.stalled without moving. critical true gives a critical result (azoospermia) and a result.critical event.
results_getResults for an order at result_received: structured values with reference ranges, Hera's analysis (versioned), the critical flag, and the lab's PDF (live only).
webhooks_createRegisters an https endpoint for events (order.created, order.document_ready, order.delivered_to_lab, appointment.booked, order.visited, result.received, result.critical, order.stalled, order.cancelled). Returns the signing secret once: verify Hera-Signature (t=…,v1=HMAC-SHA256 of "t.body") and refuse t older than 5 minutes.
webhooks_listYour webhook endpoints (secrets are never shown again).
webhooks_deleteStops sending to an endpoint.

REST

GET    /api/v1/labs?zip=&test=
POST   /api/v1/patients
GET    /api/v1/patients/:id
POST   /api/v1/orders                 (Idempotency-Key header or requestId)
GET    /api/v1/orders  ·  GET /api/v1/orders/:id
POST   /api/v1/orders/:id/cancel
POST   /api/v1/orders/:id/simulate    (sandbox)
GET    /api/v1/orders/:id/results
POST   /api/v1/webhook-endpoints  ·  GET  ·  DELETE /:id

Order journey

created → document_ready → delivered_to_lab → appointment_booked → visited → result_received, or cancelled. orders/:id returns the stage, since when, the next step, who owns it and when it is due.

Webhooks

Events: order.created, order.document_ready, order.delivered_to_lab, appointment.booked, order.visited, result.received, result.critical, order.stalled, order.cancelled. Each POST carries Hera-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 of "<t>.<raw body>" with your endpoint secret. Refuse a t more than 5 minutes old. A non-2xx answer is retried after 1, 5, 30, 120, 360 and 720 minutes. Endpoints must be https on a public host.

const [t, v1] = header.match(/^t=(\d+),v1=([0-9a-f]+)$/).slice(1);
const ok = Math.abs(Date.now()/1000 - t) < 300 &&
  crypto.timingSafeEqual(Buffer.from(v1, 'hex'),
    crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest());

Sandbox rules

All developer docs · Public lab-search MCP · Privacy · Terms