HealthSetu API
The HealthSetu API allows healthcare providers to programmatically manage diagnostic tests, availability slots, booking statuses, and lead integrations. Our API follows RESTful conventions, uses standard HTTP verbs, and returns JSON-encoded responses.
https://healthsetu.app/api/v1
Authentication
The HealthSetu API uses API keys to authenticate requests. Create and revoke keys in the partner portal under Providers → your center → API Keys. Keys are available once your center is approved. Your API keys carry many privileges, so be sure to keep them secure!
Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Authorization: Bearer YOUR_API_KEY
Errors
HealthSetu uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx indicate an error on your end, and 5xx indicate an error on our end.
| Status Code | Summary |
|---|---|
| 200 - OK | Everything worked as expected. |
| 400 - Bad Req | The request was unacceptable, often missing a required parameter. |
| 401 - Unauth | No valid API key was provided. |
| 403 - Forbidden | The API key doesn't have permissions for the request. |
| 404 - Not Found | The requested resource doesn't exist. |
| 422 - Unproc | The request was well-formed but could not be processed natively. |
| 429 - Too Many Requests | You've hit the rate limit. Exponential backoff is recommended. |
| 5xx - Server Error | Something went wrong on HealthSetu's end. (Rare) |
Create Test
Adds a single diagnostic test to your provider catalog.
/provider/tests
Body Parameters
HealthSetu test code (e.g. "CBC", "HBA1C"). Tests are matched on this code.
The name of the test (e.g. "Complete Blood Count").
Price in paise (INR × 100), e.g. 50000 for ₹500.
Your internal code for this test.
Whether home sample collection is available.
Turnaround time in hours from sample collection.
The specimen required (e.g. "blood", "urine", "saliva").
curl -X POST https://healthsetu.app/api/v1/provider/tests \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"test": {
"code": "CBC",
"name": "Complete Blood Count",
"price_cents": 50000,
"tat_hours": 24,
"sample_type": "blood"
}
}'
Bulk Upload Tests
Upload multiple tests in a single request to synchronize your complete catalog.
/provider/tests/bulk
Body Parameters
An array of test objects with the same fields as Create Test (code, name, price_cents, ...).
curl -X POST https://healthsetu.app/api/v1/provider/tests/bulk \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"tests": [
{ "code": "LIPID", "name": "Lipid Profile", "price_cents": 80000 },
{ "code": "TFT", "name": "Thyroid Profile", "price_cents": 60000 }
]
}'
Manage Slots
Push the latest availability for tests in your catalog. Each snapshot replaces the previous one for that test.
/provider/slots
Body Parameters
An array of availability snapshots, one per test.
HealthSetu test code already in your catalog (e.g. "CBC"). Unknown codes return 404.
Availability snapshot, stored as sent. Recommended shape: dates mapped to open time slots.
curl -X POST https://healthsetu.app/api/v1/provider/slots \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"slots": [
{
"test_code": "CBC",
"availability": {
"2026-10-12": ["08:00", "09:30", "11:00"],
"2026-10-13": ["08:00", "10:00"]
}
}
]
}'
Status Updates
Update the status of a HealthSetu booking assigned to your center. Only the fields you send are changed.
/provider/status_updates
Body Parameters
HealthSetu booking reference sent in the booking webhook (e.g. "HOS-3F9A1C2B7D").
One of confirmed, collected, reported, cancelled, failed.
Your internal order or accession ID.
When the sample was collected.
When the report was released.
Free-text notes for the patient or HealthSetu support.
curl -X POST https://healthsetu.app/api/v1/provider/status_updates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"booking_reference": "HOS-3F9A1C2B7D",
"status": "collected",
"provider_reference": "AP-778812",
"collected_at": "2026-10-12T09:15:00+05:30",
"fulfillment_notes": "Sample collected at home"
}'
Push Leads
Respond to a lead HealthSetu routed to your center via the lead_push webhook, e.g. to acknowledge it or send a quote.
/provider/leads/push
Body Parameters
The lead_id from the lead_push webhook. Leads not routed to your center return 404.
Your response. Defaults to received; send quoted with a quote to mark the lead as quoted.
Quoted price in paise (INR × 100), e.g. 49900 for ₹499.
Promised report turnaround in hours.
Message for the patient, such as available collection windows.
curl -X POST https://healthsetu.app/api/v1/provider/leads/push \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"lead_id": 4821,
"status": "quoted",
"quote_amount_cents": 49900,
"turnaround_hours": 24,
"note": "Home collection available tomorrow, 8-11 AM"
}'