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.
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"
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.
| Tool | What it does |
|---|---|
labs_search | Labs 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_create | Creates 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_get | One of your patients by id. |
orders_create | Orders 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_get | One order with its journey: the stage, since when, the next step, who owns it and when it is due, and the history. |
orders_list | Your most recent orders. |
orders_cancel | Cancels an order that has not been to the lab yet. |
orders_simulate | Sandbox 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_get | Results 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_create | Registers 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_list | Your webhook endpoints (secrets are never shown again). |
webhooks_delete | Stops sending to an endpoint. |
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
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.
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());
All developer docs · Public lab-search MCP · Privacy · Terms