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.

Base URL 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.

Example Header
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.

POST /provider/tests

Body Parameters

code Required

HealthSetu test code (e.g. "CBC", "HBA1C"). Tests are matched on this code.

name Required

The name of the test (e.g. "Complete Blood Count").

price_cents Required

Price in paise (INR × 100), e.g. 50000 for ₹500.

provider_code String

Your internal code for this test.

home_collection Boolean

Whether home sample collection is available.

tat_hours Number

Turnaround time in hours from sample collection.

sample_type String

The specimen required (e.g. "blood", "urine", "saliva").

cURL Request
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.

POST /provider/tests/bulk

Body Parameters

tests Required

An array of test objects with the same fields as Create Test (code, name, price_cents, ...).

cURL Request
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.

POST /provider/slots

Body Parameters

slots Required

An array of availability snapshots, one per test.

slots[].test_code Required

HealthSetu test code already in your catalog (e.g. "CBC"). Unknown codes return 404.

slots[].availability Object

Availability snapshot, stored as sent. Recommended shape: dates mapped to open time slots.

cURL Request
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.

POST /provider/status_updates

Body Parameters

booking_reference Required

HealthSetu booking reference sent in the booking webhook (e.g. "HOS-3F9A1C2B7D").

status String

One of confirmed, collected, reported, cancelled, failed.

provider_reference String

Your internal order or accession ID.

collected_at ISO 8601

When the sample was collected.

reported_at ISO 8601

When the report was released.

fulfillment_notes String

Free-text notes for the patient or HealthSetu support.

cURL Request
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.

POST /provider/leads/push

Body Parameters

lead_id Required

The lead_id from the lead_push webhook. Leads not routed to your center return 404.

status String

Your response. Defaults to received; send quoted with a quote to mark the lead as quoted.

quote_amount_cents Integer

Quoted price in paise (INR × 100), e.g. 49900 for ₹499.

turnaround_hours Integer

Promised report turnaround in hours.

note String

Message for the patient, such as available collection windows.

cURL Request
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"
  }'