Integrating Indian diagnostic-lab APIs: what the documentation does not tell you

Home-collection diagnostics is one of the most useful things a healthcare app can offer and one of the most annoying to integrate. Over a few months we connected three national lab networks to one app. Each exposed roughly the same four capabilities: check whether a pincode is served, list tests with prices, pick a slot, place a booking. Each did it differently. Here is what we learned.

Read the Postman collection, not the PDF

One partner's PDF overview was dated several years earlier and described fourteen steps and a table of status codes. The real specification was a public Postman collection with seventy-one endpoints, eleven of them deprecated. The collection was the truth; the PDF was history. Download the collection, generate a readable dump of every endpoint and body, and work from that.

Nothing answers until your IP is allow-listed

Staging environments for all three partners sat behind IP allow-lists or load balancers with no healthy backend. Before any work, register the egress IPs of every environment you will call from: developer machines, your demo server, and production. One partner's staging returned a 503 from one network and a 403 from another. Neither was our bug.

The checksum is in the partner portal's JavaScript

One partner signs requests with a checksum whose algorithm was not in any document we received. It was in their partner portal's front-end bundle: an HMAC-SHA256 of the request body with a key from the portal, hex-encoded. We documented it, built it, and asked them to confirm. They did.

Every partner has a different idea of a webhook

• One sends dozens of distinct event types, from collector assigned to report uploaded, each with its own payload shape.
• One has a staging trigger you can call to simulate events, which sometimes times out after two minutes and then delivers anyway.
• One could not be tested at all for weeks because its staging host was down and its vendor's domain had stopped resolving.

Design for this. We treat every webhook as untrusted input: verify the signature, map the partner's status to our own small set of statuses, store the raw payload, and make the mapping a table rather than code.

The connector layer

What kept the app simple was a connector layer that made each partner look like one more lab in our own database. The app asks "is this pincode served, what are the tests, what slots are free, place this booking" through one interface. A driver per partner translates. A per-partner kill switch lets us disable one network without a deploy. A mock driver with fixtures lets us build and test the whole flow before a single real credential arrives.

Prepaid versus cash on collection

Partners disagree on payment. One accepts cash on collection; one is prepaid only. Our checkout had to express that per lab, with a clear message, rather than discovering it at booking time.

What to ask on day one

1. The live Postman or OpenAPI link, not the PDF.
2. The IP allow-list procedure for staging and production.
3. The signing algorithm, with a worked example.
4. The full webhook event list and whether staging can trigger them.
5. Commercial terms: visit charges, minimum order, prepaid rules.

Get those and the integration is a few weeks. Skip them and it is a few months.