EUA — Phase 2: Discovery (Doctor Search)
The Discovery phase lets a patient (EUA) find available doctors across the UHI network. There are two search modes:
| Mode | How it works |
|---|---|
| Broadcast | EUA sends one request to the Gateway; Gateway fans out to all registered HSPAs |
| Direct P2P | EUA sends directly to a specific HSPA for slot-level availability |
Broadcast Search Flow
Direct P2P Search Flow
Used after a broadcast search to get slot-level detail for a specific doctor from a specific HSPA.
API Endpoints
POST /uhi/search — Initiate search
Auth required: Yes (Kulcare JWT Bearer token)
Request body:
{
"service_type": "physical",
"transaction_id": "txn-abc123",
"intent": {
"category": {
"descriptor": { "code": "CARDIOLOGY", "name": "Cardiology" }
},
"fulfillment": {
"type": "Physical",
"start": { "time": { "timestamp": "2026-04-17T00:00:00" } },
"end": { "time": { "timestamp": "2026-04-17T23:59:59" } }
},
"item": {
"descriptor": { "code": "Consultation", "name": "Consultation" }
},
"location": {
"city": { "name": "Delhi", "code": "011" }
}
}
}For direct P2P, also include:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"intent": {
"provider": { "id": "1" },
"fulfillment": { "type": "Physical" }
}
}Response:
{
"success": true,
"transaction_id": "txn-abc123",
"message": "Search broadcast sent"
}Returns immediately with ACK. Results arrive asynchronously via on_search callbacks.
GET /uhi/search/:transaction_id/results — Poll results
Auth required: Yes
Response:
{
"success": true,
"transaction_id": "txn-abc123",
"catalogs": [
{
"descriptor": { "name": "Apollo Hospitals" },
"providers": [
{
"id": "1",
"descriptor": { "name": "Apollo Delhi" },
"categories": [
{ "id": "201", "descriptor": { "code": "CARDIOLOGY", "name": "Cardiology" } }
],
"fulfillments": [
{
"id": "slot-uuid-abc",
"type": "Physical",
"agent": { "id": "drsmith@hpr.ndhm", "name": "Dr. Smith" },
"start": { "time": { "timestamp": "2026-04-17T10:00:00" } },
"end": { "time": { "timestamp": "2026-04-17T10:20:00" } }
}
],
"items": [
{ "id": "0", "price": { "currency": "INR", "value": "500.0" } }
]
}
]
}
]
}on_search Callback (Inbound)
Endpoint: POST /uhi/on_search
Auth: UHI Authorization header (verified by UhiController)
Caller: HSPA (async, after receiving broadcast search from Gateway)
The callback logs the full catalog and marks the webhook as processed. The transaction_id in the context links this callback to the original outbound search request.
{
"context": {
"domain": "nic2004:85111",
"action": "on_search",
"provider_id": "hspa-nha",
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"consumer_id": "kulcare.eua",
"consumer_uri": "https://api-stg.kulcare.com/uhi",
"transaction_id": "txn-abc123",
"message_id": "msg-xyz"
},
"message": {
"catalog": {
"descriptor": { "name": "NHA Sandbox HSPA" },
"providers": [ ... ]
}
}
}Response (always):
{ "message": { "ack": { "status": "ACK" } }, "error": {} }Key Implementation Notes
transaction_idmust be consistent across the search request and allon_searchcallbacks so results can be correlated.- Multiple HSPAs may respond to a single broadcast — each sends its own
on_search. Poll/resultsafter a suitable delay (e.g., 3–5 seconds). - The
provider_uriin theon_searchcontext is needed for all subsequent P2P calls (/init,/confirm,/status,/cancel). Store it alongside the fulfillment ID. fulfillment.id(slot UUID) is used asfulfillment_idin the/initrequest.