Physical consultation

Physical consultation is the fullest service on UHI. A patient searches for a doctor, then sees real slots and fees from clinics they have no prior relationship with. They book one, and receive a 4-digit PIN to present at the clinic. After this page you will know the four stages, the endpoints each role exposes, and the fields on every call, as NHA documents them.

Read UHI services first, for the context block, the acknowledgement model, signing and the two transports.

Where this service stands​

The full consultation lifecycle is the first phase, live and open for onboarding. Online payment and refunds are the second phase, in ideation. Today the only payment model is pay on visit.

Service identity​

Every call in this service carries these fixed values.

Who is involved​

The flow end to end​

Stage by stage​

Endpoints you expose​

An HSPA exposes these. Everything except the first search is called by an EUA directly.

An EUA exposes these. Everything except the first on_search is called by the HSPA directly.

Stage 1: discovery​

First search, broadcast​

Your EUA posts to the gateway. The gateway validates your signature and the domain, then forwards to every registered HSPA in that domain. Search filters go in message.intent.

POST https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search

A search by state and district:

{
  "context": {
    "action": "search",
    "city": "std:011",
    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",
    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",
    "core_version": "0.7.1",
    "country": "IND",
    "domain": "nic2004:85111",
    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",
    "timestamp": "2026-06-18T06:52:13.969464Z",
    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"
  },
  "message": {
    "intent": {
      "fulfillment": {
        "type": "Physical",
        "start": { "time": { "timestamp": "2026-06-18T10:37:32" } },
        "end": { "time": { "timestamp": "2026-06-18T23:59:59" } }
      },
      "item": {
        "descriptor": { "code": "Consultation", "name": "Consultation" }
      },
      "location": {
        "state": { "name": "MAHARASHTRA", "code": "27" },
        "district": { "name": "PUNE", "code": "490" }
      }
    }
  }
}

Three warnings apply to this call:

• A GPS search needs all three radius fields. Omit any one and the GPS filter is ignored without an error.
• The transaction_id in search must match the one in the on_search that answers it, or you cannot correlate the response.
• More filter combinations exist. The Swagger spec is the list.

First on_search, the catalog​

Each matching HSPA answers independently, so you receive several. Aggregate them on transaction_id.

Trimmed to one provider:

{
  "context": {
    "domain": "nic2004:85111",
    "action": "on_search",
    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",
    "provider_id": "hspa-nha",
    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
    "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
    "message_id": "b2c3d4e5-f951-11ec-b135-53aea776f66b"
  },
  "message": {
    "catalog": {
      "descriptor": { "name": "ABDM Reference HSPA" },
      "providers": [
        {
          "id": "1",
          "descriptor": { "name": "Safdarjung Medical Centre" },
          "categories": [
            { "id": "201", "parent_category_id": "101", "descriptor": { "name": "Cardiology", "code": "CARDIOLOGY" } },
            { "id": "101", "descriptor": { "name": "Allopathy", "code": "ALLOPATHY" } }
          ],
          "fulfillments": [
            {
              "id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef",
              "type": "Physical",
              "agent": {
                "id": "priyamehra@hpr.ndhm",
                "name": "Dr. Priya Mehra",
                "gender": "F",
                "tags": {
                  "@abdm/gov.in/experience": "8.0",
                  "@abdm/gov.in/languages": "Hindi, English",
                  "@abdm/gov.in/education": "MBBS, MD Cardiology",
                  "@abdm/gov.in/hpr_id": "73-5232-1888-8686"
                }
              },
              "start": { "time": { "timestamp": "2026-04-16T10:00:00" } },
              "end": { "time": { "timestamp": "2026-04-16T10:20:00" } }
            }
          ],
          "items": [
            {
              "id": "0",
              "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
              "price": { "currency": "INR", "value": "500.0" },
              "fulfillment_id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef"
            }
          ],
          "location": {
            "gps": "28.635308,77.224960",
            "address": "Safdarjung Enclave, New Delhi 110029",
            "city": { "name": "Delhi", "code": "011" }
          }
        }
      ]
    }
  }
}

An HSPA sends the full agent.tags set including @abdm/gov.in/hip_id. That ID is what lets records generated at the visit be pulled later.

Second search, direct​

After the patient picks a doctor, your EUA sends a second search straight to the HSPA's provider_uri, asking for that doctor's slots in a time window. It carries provider_id and provider_uri in the context, and echoes the provider, fulfillments and items blocks from the first on_search. The HSPA answers with a second on_search scoped to that doctor.

Stage 2: booking​

init​

Direct to the HSPA. You send the patient's details and the chosen slot. The HSPA holds the slot temporarily.

{
  "context": {
    "domain": "nic2004:85111",
    "country": "IND",
    "city": "std:011",
    "action": "init",
    "core_version": "0.7.1",
    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",
    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",
    "provider_id": "hspa-nha",
    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
    "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
    "message_id": "d4e5f6a7-32af-11ef-bcbe-590b07ce8c90",
    "timestamp": "2026-04-15T09:10:00Z"
  },
  "message": {
    "order": {
      "provider": { "id": "1" },
      "item": {
        "id": "0",
        "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
        "price": { "currency": "INR", "value": "500.0" },
        "fulfillment_id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef"
      },
      "fulfillment": {
        "id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef",
        "type": "Physical",
        "agent": { "id": "priyamehra@hpr.ndhm", "name": "Dr. Priya Mehra" },
        "start": { "time": { "timestamp": "2026-04-16T10:00:00" } },
        "end": { "time": { "timestamp": "2026-04-16T10:20:00" } }
      },
      "billing": {
        "name": "Rahul Kumar Sharma",
        "address": {
          "door": "B-204",
          "name": "Rahul Kumar Sharma",
          "locality": "Rohini Sector 14",
          "city": "Delhi",
          "state": "Delhi",
          "country": "INDIA",
          "area_code": "110085"
        },
        "phone": "9876543210",
        "email": "rahul.sharma@email.com"
      },
      "customer": {
        "id": "rahul.k001@sbx",
        "person": { "gender": "M", "dob": "1990-05-15", "dayOfBirth": 15, "monthOfBirth": 5, "yearOfBirth": 1990 }
      },
      "payment": {
        "type": "ON-ORDER",
        "params": { "redirect_url": "<YOUR_PAYMENT_REDIRECT_URL>" }
      }
    }
  }
}

Two warnings:

• fulfillment.id must be exactly the slot UUID from on_search. A mismatch makes the HSPA reject the call or fail to hold the slot without telling you.
• The hold is short, typically 15 minutes. If confirm does not arrive in time the slot is released and you start again at init.

on_init, the terms​

The HSPA answers with the order ID, an itemised quote, and five term objects the patient has to accept.

Each term object:

Store every term object exactly as received. Change only termsState, and reason where it is required.

confirm​

Send the whole order back with every term at AGREED. Any term still at INITIATED and the HSPA rejects the call. Use the order.id the HSPA assigned in on_init, not any ID you generated.

on_confirm, the PIN​

The HSPA sets order.state to CONFIRMED and returns a 4-digit PIN.

{
  "authorization": {
    "type": "PIN",
    "token": "3774",
    "valid_from": "2026-06-18T00:00:00",
    "valid_to": "2026-06-18T23:59:00",
    "status": "GENERATED"
  }
}

The PIN is security sensitive. Hold it in memory or secure session storage on the EUA. Do not write it to a database or to application logs.

The HSPA has two more obligations here. It sends an exact copy of the on_confirm payload to the gateway audit endpoint listed under gateway endpoints, and it sets the communication tags on the fulfilment:

{
  "tags": {
    "@abdm/gov.in/slot_id": "79db6b5b-afe4-4297-b9b1-5148ed45372c",
    "@abdm/gov.in/messaging_support": "true",
    "@abdm/gov.in/deep_link": "",
    "@abdm/gov.in/helpline_number": "",
    "@abdm/gov.in/chatbot_link": ""
  }
}

messaging_support and a helpline number are mandatory in on_confirm.

Stage 3: fulfilment​

status and on_status​

status carries only order.id. The HSPA answers with the full order object, and you replace your stored state with it. This is reconciliation, not a polling loop.

Order states​

DOCTOR_NO_SHOW is the only state an EUA may set. Everything else is the HSPA's.

PIN states​

on_update​

The HSPA pushes state changes to your /on_update as they happen. This is the main real-time channel, not status. Update your local state and notify the patient.

Stage 4: post-fulfilment​

cancel and on_cancel​

{
  "message": {
    "order": {
      "id": "0415-234567-8901",
      "state": "CANCELLED",
      "fulfillment": {
        "tags": { "@abdm/gov.in/cancelledby": "patient" }
      }
    }
  }
}

The cancelledby tag is mandatory. Without it the HSPA cannot tell which set of cancellation terms applies.

Your /on_cancel handler has to cope with both directions: the HSPA's acknowledgement of a patient cancellation, and an HSPA-initiated cancellation when a doctor cancels. Read the cancelledby tag to tell them apart.

on_message​

Optional for an HSPA, mandatory for an EUA. Both sides consume the same shape. Content sits under message.intent.chat.

Gateway endpoints​

You do not build these. NHA operates them.

The audit copies are an HSPA obligation for compliance traceability, not optional.

Cancellation reason codes​

The reason codes are fixed. You choose the labels your users see.

Patient-initiated, sent in cancel with cancelledby: patient​

Doctor or facility-initiated, sent in on_cancel with cancelledby: doctor​

PIN override, used by facility staff​

Terms and conditions text​

The on_init terms array carries the text the patient reads before confirming. Sample clauses are published. Two points carry through all of them.

• UHI is a technology gateway. It does not supervise providers, does not guarantee outcomes, and does not collect, hold or route any payment.
• Every payment, refund, cancellation charge and pricing dispute is between the patient and the facility.

Field and error reference​

The tables above carry the fields you send and receive most. For the complete order field list, use the Swagger spec.

Error codes for this service are not published as a list. The error object carries type and code, both mandatory, with path and message optional.

Next​

• UHI services for the shared protocol
• Ambulance booking
• Blood bank
• M2, the prerequisite
• Support