Physical Consultation

Use UHI Physical Consultation to discover doctors, book a clinic visit, verify a PIN, and track the appointment lifecycle.

UHI Physical Consultation lets an EUA discover doctors and book a physical clinic visit through an HSPA. The service uses UHI core version 0.7.1 and domain nic2004:85111.

Parameter	Value
Domain code	`nic2004:85111`
Core version	`0.7.1`
Service type	Physical Consultation (Payment on Visit)
Owner	NHA

This page gives the service flow only. See Network and protocol for the shared context block, the signature process, ACK/NACK, callbacks, and Gateway endpoints.

Use Onboarding for sandbox access and production go-live.

Architecture

Use Gateway only for discovery

Discovery goes through the Gateway. Booking, fulfilment, and post-fulfilment use direct P2P calls between the EUA and the HSPA.

The EUA sends the first search call to the Gateway. The Gateway broadcasts the request to each registered HSPA in domain nic2004:85111.

After the patient selects a doctor, the EUA sends all service calls to the HSPA provider_uri.

Actors

Actor	Full name	Role
EUA	End User Application	Show search results, start booking, and show appointment state to the patient.
HSPA	Health Service Provider Application	Manage doctor profiles, slots, appointment state, and provider callbacks.
HSP	Health Service Provider	Run the clinic, hospital, or doctor service.
Gateway	UHI Gateway	Route discovery calls and accept audit payloads.
NHA	National Health Authority	Own the service and operate the network.

Full flow

sequenceDiagram
autonumber
participant EUA
participant Gateway
participant HSPA
participant HSP
EUA->>Gateway: POST /api/v1/uhi/search
Gateway->>HSPA: POST /search
HSPA->>Gateway: POST /api/v1/uhi/on_search
Gateway->>EUA: POST /on_search
EUA->>HSPA: POST /search (P2P)
HSPA->>EUA: POST /on_search (P2P)
EUA->>HSPA: POST /init
HSPA->>EUA: POST /on_init
EUA->>HSPA: POST /confirm
HSPA->>EUA: POST /on_confirm with PIN
HSP->>HSPA: Verify PIN
EUA->>HSPA: POST /status
HSPA->>EUA: POST /on_status
EUA->>HSPA: POST /on_update with DOCTOR_NO_SHOW
HSPA->>EUA: POST /on_update with appointment state
EUA->>HSPA: POST /cancel
HSPA->>EUA: POST /on_cancel

Service identity

Use these fixed identifiers in each Physical Consultation call.

Field	Value
`context.domain`	`nic2004:85111`
`message.intent.fulfillment.type`	`Physical`
`message.intent.item.descriptor.code`	`Consultation`
`message.intent.item.descriptor.name`	`Consultation`
`context.core_version`	`0.7.1`

Environment

Parameter	Sandbox value
Gateway base URI	`https://uhigatewaysandbox.abdm.gov.in`
Reference EUA URI	`http://uhieuasandbox.abdm.gov.in/api/v1/euaService`
Reference HSPA URI	`https://hspasbx.abdm.gov.in/api/v1/hspa`

Endpoint checklists

HSPA endpoints

Expose these HTTPS endpoints on the HSPA.

Endpoint	When	Action	Caller
`/search` first	After a discovery search	Accept intent and return catalog through `/on_search`.	Gateway
`/search` second	After doctor selection	Return slots for the selected doctor.	EUA
`/init`	After booking start	Hold the slot and return terms through `/on_init`.	EUA
`/confirm`	After patient consent	Confirm the appointment and return a PIN.	EUA
`/status`	When EUA needs status	Return current order state through `/on_status`.	EUA
`/cancel`	After patient cancel	Process cancel and return `/on_cancel`.	EUA
`/on_update`	When state changes	Accept EUA state `DOCTOR_NO_SHOW`.	EUA
`/on_message`	When patient sends chat	Accept text or media from the EUA.	EUA

EUA endpoints

Expose these HTTPS endpoints on the EUA.

Endpoint	When	Action	Caller
`/on_search` first	After Gateway search	Store HSPA `provider_uri` and show catalog.	Gateway
`/on_search` second	After direct search	Show slots for the selected doctor.	HSPA
`/on_init`	After HSPA holds slot	Show terms and store `order.id`.	HSPA
`/on_confirm`	After HSPA confirms	Show the PIN and store the order.	HSPA
`/on_status`	After status request	Replace the local order state.	HSPA
`/on_update`	When state changes	Update patient view and notify the patient.	HSPA
`/on_cancel`	After cancel	Mark the order as cancelled.	HSPA
`/on_message`	When provider sends chat	Accept text or media from the HSPA.	HSPA

Gateway endpoints

Call these NHA endpoints as required.

Endpoint	Caller	Purpose
`/api/v1/uhi/search`	EUA	Start broadcast discovery.
`/api/v1/uhi/on_search`	HSPA	Send catalog responses to the EUA through the Gateway.
`/api/v1/uhi/on_confirm_audit`	HSPA	Send a copy of each `on_confirm` payload.
`/api/v1/uhi/on_update_audit`	HSPA	Send a copy of each `on_update` payload.
`/api/v1/uhi/on_cancel_audit`	HSPA	Send a copy of each `on_cancel` payload.
`/api/v1/uhi/on_status_audit`	HSPA	Send a copy of each `on_status` payload.
`/api/v1/networkregistry/lookup`	EUA or HSPA	Look up a subscriber public key and details.

Discovery

Discovery has 2 rounds. Use the Gateway for the first round. Use direct P2P for the second round.

The examples keep short arrays. See the source Swagger for the full field list.

Search filters need exact fields

Search can use GPS, state, district, doctor name, HPR ID, pincode, or facility name. For GPS search, send radius.type, radius.value, and radius.unit. Keep the same transaction_id in search and on_search.

First search: EUA to Gateway to HSPA

Key field	Use
`context.action`	Set `search`.
`context.domain`	Set `nic2004:85111`.
`message.intent.fulfillment.type`	Set `Physical`.
`message.intent.item.descriptor`	Set code and name to `Consultation`.
`message.intent.location`	Send the search location or radius fields.

POST/search

The EUA starts broadcast discovery through the Gateway.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "search",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "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" }
    }
  }
}
}

Store each provider URI

The EUA can receive more than 1 on_search. Aggregate results by transaction_id and store each context.provider_uri.

First on_search: Gateway to EUA callback

Key field	Use
`context.provider_uri`	Store it for P2P calls.
`message.catalog.providers[].id`	Use it as the provider ID.
`message.catalog.providers[].fulfillments[]`	Use it for doctor and slot data.
`message.catalog.providers[].items[]`	Use `item.id` and `fulfillment_id` in booking.
`message.catalog.providers[].location`	Show the clinic address and GPS.

POST/on_search

The EUA receives provider catalog data through its callback URL.

cURL

curl -X POST "https://uhieuasandbox.abdm.gov.in/api/v1/euaService/on_search" \
-H "Content-Type: application/json" \
-H "X-Gateway-Authorization: <gateway-signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_search",
  "consumer_id": "eua-nha",
  "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" }
          }
        ],
        "fulfillments": [
          {
            "id": "slot-uuid-a1",
            "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" } }
          },
          {
            "id": "slot-uuid-a2",
            "type": "Physical",
            "agent": { "id": "priyamehra@hpr.ndhm", "name": "Dr. Priya Mehra" },
            "start": { "time": { "timestamp": "2026-04-16T10:20:00" } },
            "end": { "time": { "timestamp": "2026-04-16T10:40:00" } }
          }
        ],
        "items": [
          {
            "id": "0",
            "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
            "price": { "currency": "INR", "value": "500.0" },
            "fulfillment_id": "slot-uuid-a1"
          }
        ],
        "location": {
          "gps": "28.635308,77.224960",
          "address": "Safdarjung Enclave, New Delhi 110029",
          "city": { "name": "Delhi", "code": "011" }
        }
      }
    ]
  }
}
}

Second search: EUA to HSPA P2P

Key field	Use
`context.provider_id`	Copy it from first `on_search`.
`context.provider_uri`	Send the call to this base URL.
`message.intent.provider.id`	Select the provider from the catalog.
`message.intent.provider.fulfillments[].agent.id`	Select the doctor HPR ID.
`message.intent.fulfillment.start/end`	Define the slot window.

POST/search

The EUA asks the selected HSPA for slots for one doctor.

cURL

curl -X POST "<provider_uri>/search" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "search",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "message_id": "c3d4e5f6-32af-11ef-bcbe-590b07ce8c90",
  "timestamp": "2026-04-15T09:05:00Z",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b"
},
"message": {
  "intent": {
    "provider": {
      "id": "1",
      "categories": [
        {
          "id": "201",
          "parent_category_id": "101",
          "descriptor": { "name": "Cardiology", "code": "CARDIOLOGY" }
        }
      ],
      "fulfillments": [
        {
          "type": "Physical",
          "agent": { "id": "priyamehra@hpr.ndhm" },
          "start": { "time": { "timestamp": "2026-04-16T00:00:00" } },
          "end": { "time": { "timestamp": "2026-04-16T23:59:59" } }
        }
      ],
      "items": [
        {
          "id": "0",
          "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
          "price": { "currency": "INR", "value": "500.0" },
          "fulfillment_id": "slot-uuid-a1"
        }
      ]
    },
    "fulfillment": {
      "type": "Physical",
      "agent": { "id": "priyamehra@hpr.ndhm" },
      "start": { "time": { "timestamp": "2026-04-16T00:00:00" } },
      "end": { "time": { "timestamp": "2026-04-16T23:59:59" } }
    },
    "item": { "descriptor": { "code": "Consultation", "name": "Consultation" } }
  }
}
}

Send required doctor tags

Send all doctor tags with the HIP ID. The EUA needs them to show prescriptions and health records.

Second on_search: HSPA to EUA P2P

Key field	Use
`context.action`	Set `on_search`.
`message.catalog.providers[].fulfillments[]`	Return only the selected doctor slot set.
`message.catalog.providers[].items[].price`	Return the consultation fee.
`message.catalog.providers[].items[].fulfillment_id`	Link each item to the slot.
`message.catalog.providers[].location`	Return the clinic location.

POST/on_search

The HSPA returns the selected doctor slots directly to the EUA.

cURL

curl -X POST "<consumer_uri>/on_search" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "on_search",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "http://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b",
  "message_id": "e9a19230-f951-11ec-b135-53aea776f66b"
},
"message": {
  "catalog": {
    "descriptor": { "name": "Ref HSPA" },
    "providers": [
      {
        "id": "1",
        "descriptor": { "name": "Test Hospital" },
        "categories": [
          {
            "id": "0",
            "parent_category_id": "101",
            "descriptor": { "name": "Cardiology", "code": "CARDIOLOGY" }
          }
        ],
        "fulfillments": [
          {
            "id": "0",
            "type": "Physical",
            "agent": {
              "id": "ganeshborse@hpr.ndhm",
              "name": "Ganesh Vikram Borse",
              "gender": "M",
              "tags": {
                "@abdm/gov.in/experience": "10.0",
                "@abdm/gov.in/languages": "Hindi, English",
                "@abdm/gov.in/education": "MBBS, BDS",
                "@abdm/gov.in/hpr_id": "73-5232-1888-8686",
                "@abdm/gov.in/hfr_id": "73-5232-1888-8687",
                "@abdm/gov.in/hip_id": "IN2910000074"
              }
            },
            "start": { "time": { "timestamp": "2023-01-03T12:30:00" } },
            "end": { "time": { "timestamp": "2023-01-03T12:45:00" } }
          }
        ],
        "items": [
          {
            "id": "0",
            "descriptor": { "name": "Consultation" },
            "price": { "currency": "INR", "value": "300.0" },
            "category_id": "0",
            "fulfillment_id": "0"
          }
        ],
        "location": {
          "id": "1",
          "city": { "name": "Delhi", "code": "011" },
          "gps": "18.5246036,73.792927",
          "address": "Connaught Place, New Delhi, Delhi 110001"
        }
      }
    ]
  }
}
}

Booking

Booking uses direct P2P. The EUA calls init and confirm. The HSPA returns on_init and on_confirm.

Use the exact slot ID

The fulfillment.id in init must match the slot UUID from on_search. The HSPA can hold the slot for about 15 minutes.

init: EUA to HSPA P2P

Key field	Use
`order.provider.id`	Copy the provider ID from `on_search`.
`order.item.id`	Copy the item ID from `on_search`.
`order.fulfillment.id`	Copy the selected slot UUID.
`order.billing`	Send patient bill data.
`order.customer.id`	Send the patient ABHA ID.
`order.payment.type`	Set `ON-ORDER` for pay on visit.

POST/init

The EUA asks the HSPA to hold the selected slot.

cURL

curl -X POST "<provider_uri>/init" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "init",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "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-a1"
    },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" }
    },
    "payment": {
      "type": "ON-ORDER",
      "params": { "redirect_url": "https://uhieuasandbox.abdm.gov.in/on_paymentStatus" }
    }
  }
}
}

on_init: HSPA to EUA P2P

Key field	Use
`order.id`	Store the HSPA order ID.
`order.terms[]`	Show each term to the patient.
`order.terms[].termsState`	Expect `INITIATED`.
`order.quote`	Show the price break-up.
`order.payment.status`	Show the initial payment state.

POST/on_init

The HSPA returns the order ID, terms, quote, and payment state.

cURL

curl -X POST "<consumer_uri>/on_init" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_init",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "e5f6a7b8-32af-11ef-bcbe-590b07ce8c90"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "provider": { "id": "1" },
    "item": {
      "id": "0",
      "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
      "price": { "currency": "INR", "value": "500.0" },
      "fulfillment_id": "slot-uuid-a1"
    },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" } },
      "tags": { "@abdm/gov.in/slot_id": "slot-uuid-a1" }
    },
    "terms": [
      { "type": "Commercial", "descriptor": { "name": "Commercial Terms", "short_desc": "Commercial terms for this consultation.", "long_desc": "Full commercial terms text." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "INITIATED" },
      { "type": "Settlement", "descriptor": { "name": "Settlement Terms", "short_desc": "Settlement terms between EUA and HSPA.", "long_desc": "Full settlement terms text." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "INITIATED" },
      { "type": "Cancellation", "descriptor": { "name": "Cancellation Policy", "short_desc": "Full refund if cancelled 48 hrs prior.", "long_desc": "Full cancellation terms text." }, "reasonRequired": true, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "INITIATED" },
      { "type": "Refund", "descriptor": { "name": "Refund Policy", "short_desc": "Full refund if doctor does not show.", "long_desc": "Full refund terms text." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "INITIATED" },
      { "type": "Payment", "descriptor": { "name": "Payment Terms", "short_desc": "Pay at clinic on day of visit.", "long_desc": "Full payment terms text." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "INITIATED" }
    ],
    "quote": {
      "price": { "currency": "INR", "value": "500.0" },
      "breakup": [ { "title": "Consultation", "price": { "currency": "INR", "value": "500.0" } } ]
    },
    "payment": { "type": "ON-ORDER", "status": "NOT_PAID" }
  }
}
}

Do not change term objects

Store all term objects exactly as received. In confirm, only change each termsState to AGREED.

Use the HSPA order ID

The order.id in confirm must match the order.id from on_init.

confirm: EUA to HSPA P2P

Key field	Use
`order.id`	Copy the HSPA order ID from `on_init`.
`order.terms[]`	Return all terms from `on_init`.
`order.terms[].termsState`	Set each value to `AGREED`.
`order.terms[].reason`	Send a reason if `reasonRequired` is true.
`order.payment.status`	Send the current payment state.

POST/confirm

The EUA confirms that the patient accepts all terms.

cURL

curl -X POST "<provider_uri>/confirm" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "confirm",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "f6a7b8c9-3213-11ef-8788-59590da7b6ce",
  "timestamp": "2026-04-15T09:15:00Z"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "provider": { "id": "1" },
    "item": {
      "id": "0",
      "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
      "price": { "currency": "INR", "value": "500.0" },
      "fulfillment_id": "slot-uuid-a1"
    },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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", "phone": "9876543210", "email": "rahul.sharma@email.com" },
    "customer": { "id": "rahul.k001@sbx", "person": { "gender": "M", "dob": "1990-05-15" } },
    "payment": { "type": "ON-ORDER", "status": "NOT_PAID", "params": { "amount": "500.0", "redirect_url": "" } },
    "terms": [
      { "type": "Commercial", "descriptor": { "name": "Commercial Terms", "short_desc": "...", "long_desc": "..." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "AGREED" },
      { "type": "Settlement", "descriptor": { "name": "Settlement Terms", "short_desc": "...", "long_desc": "..." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "AGREED" },
      { "type": "Cancellation", "descriptor": { "name": "Cancellation Policy", "short_desc": "...", "long_desc": "..." }, "reasonRequired": true, "timePeriod": "2026-12-31T23:59:59", "reason": "Patient agreed to cancellation policy", "termsState": "AGREED" },
      { "type": "Refund", "descriptor": { "name": "Refund Policy", "short_desc": "...", "long_desc": "..." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "AGREED" },
      { "type": "Payment", "descriptor": { "name": "Payment Terms", "short_desc": "...", "long_desc": "..." }, "reasonRequired": false, "timePeriod": "2026-12-31T23:59:59", "reason": "", "termsState": "AGREED" }
    ]
  }
}
}

Protect the PIN

Treat the Physical Consultation PIN as security-sensitive. Do not store it in a database or application log. Send communication tags in on_confirm.

on_confirm: HSPA to EUA P2P

Key field	Use
`order.state`	Expect `CONFIRMED` or `FAILED`.
`order.authorization.type`	Expect `PIN` for Physical Consultation.
`order.authorization.token`	Show the 4-digit PIN to the patient.
`order.authorization.status`	Track `GENERATED`, `VERIFIED`, or `HSPA_OVERRIDE`.
`order.fulfillment.tags`	Send `messaging_support` and `helpline_number`.

POST/on_confirm

The HSPA confirms the appointment and returns a check-in PIN.

cURL

curl -X POST "<consumer_uri>/on_confirm" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "on_confirm",
  "timestamp": "2026-06-18T06:52:13.969464Z",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "f1a1a6b2-ece2-46a0-8229-9e8b5610afcc",
  "message_id": "f1a1a6b2-ece2-46a0-8229-9e8b5610afcc"
},
"message": {
  "order": {
    "id": "3714-330853-9384",
    "provider": { "id": "1" },
    "state": "CONFIRMED",
    "item": {
      "id": "0",
      "descriptor": { "name": "Consultation", "code": "CONSULTATION" },
      "price": { "currency": "INR", "value": "0.0" },
      "fulfillment_id": "79db6b5b-afe4-4297-b9b1-5148ed45372c"
    },
    "fulfillment": {
      "id": "79db6b5b-afe4-4297-b9b1-5148ed45372c",
      "type": "Physical",
      "agent": { "id": "ganeshborse@hpr.ndhm", "name": "Ganesh Vikram Borse" },
      "start": { "time": { "timestamp": "2026-06-18T16:00:00" } },
      "end": { "time": { "timestamp": "2026-06-18T16:30:00" } },
      "tags": {
        "@abdm/gov.in/slot_id": "79db6b5b-afe4-4297-b9b1-5148ed45372c",
        "@abdm/gov.in/messaging_support": "true",
        "@abdm/gov.in/helpline_number": ""
      }
    },
    "payment": { "type": "ON-ORDER", "status": "FREE", "params": { "amount": "0.0" } },
    "authorization": {
      "type": "PIN",
      "token": "3774",
      "valid_from": "2026-06-18T00:00:00",
      "valid_to": "2026-06-18T23:59:00",
      "status": "GENERATED"
    }
  }
}
}

Fulfilment

Use fulfilment calls to pull status and push appointment state changes.

status: EUA to HSPA P2P

Key field	Use
`context.action`	Set `status`.
`message.order.id`	Send the HSPA order ID.
`context.transaction_id`	Keep the lifecycle transaction ID.

POST/status

The EUA asks the HSPA for the current order state.

cURL

curl -X POST "<provider_uri>/status" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "action": "status",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "b8c9d0e1-f951-11ec-b135-53aea776f66b",
  "timestamp": "2026-04-16T09:55:00Z"
},
"message": { "order": { "id": "0415-234567-8901" } }
}

on_status: HSPA to EUA P2P

Key field	Use
`order.state`	Replace the local state with this value.
`order.payment.status`	Replace the local payment state.
`order.authorization.status`	Replace the local PIN state.
`order.fulfillment`	Replace slot and doctor data.

POST/on_status

The HSPA returns the full order state to the EUA.

cURL

curl -X POST "<consumer_uri>/on_status" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_status",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "c9d0e1f2-f951-11ec-b135-53aea776f66b"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "state": "CONFIRMED",
    "item": { "id": "0", "descriptor": { "code": "Consultation", "name": "Consultation" } },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" } }
    },
    "payment": { "type": "ON-ORDER", "status": "NOT_PAID", "params": { "amount": "500.0" } },
    "authorization": {
      "type": "PIN",
      "token": "7342",
      "valid_from": "2026-04-16T00:00:00",
      "valid_to": "2026-04-16T23:59:00",
      "status": "GENERATED"
    }
  }
}
}

on_update: EUA to HSPA P2P

Key field	Use
`order.id`	Send the HSPA order ID.
`order.state`	Send only `DOCTOR_NO_SHOW`.
`order.authorization`	Send the current PIN object.
`order.fulfillment`	Send the appointment slot.

POST/on_update

The EUA can report DOCTOR_NO_SHOW to the HSPA.

cURL

curl -X POST "<provider_uri>/on_update" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_update",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "d0e1f2a3-f951-11ec-b135-53aea776f66b",
  "timestamp": "2026-04-16T10:35:00Z"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "state": "DOCTOR_NO_SHOW",
    "item": { "id": "0", "descriptor": { "code": "Consultation", "name": "Consultation" } },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" } }
    },
    "authorization": {
      "type": "PIN",
      "token": "7342",
      "valid_from": "2026-04-16T00:00:00",
      "valid_to": "2026-04-16T23:59:00",
      "status": "GENERATED"
    }
  }
}
}

on_update: HSPA to EUA P2P

Key field	Use
`order.state`	Send `APPOINTMENT_STARTED`, `COMPLETED`, `CANCELLED`, or `NO_SHOW`.
`order.authorization.status`	Send `VERIFIED` or `HSPA_OVERRIDE` after check-in.
`order.payment`	Send the current payment state.
`order.fulfillment.agent.tags`	Send doctor metadata.

POST/on_update

The HSPA pushes appointment state changes to the EUA.

cURL

curl -X POST "<consumer_uri>/on_update" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_update",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "e1f2a3b4-f951-11ec-b135-53aea776f66b",
  "timestamp": "2026-04-16T10:05:00Z"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "state": "APPOINTMENT_STARTED",
    "item": { "id": "0", "descriptor": { "code": "Consultation", "name": "Consultation" } },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" } }
    },
    "payment": { "type": "ON-ORDER", "status": "NOT_PAID", "params": { "amount": "500.0" } },
    "authorization": {
      "type": "PIN",
      "token": "7342",
      "valid_from": "2026-04-16T00:00:00",
      "valid_to": "2026-04-16T23:59:00",
      "status": "VERIFIED"
    }
  }
}
}

Post-Fulfilment

Use post-fulfilment calls for cancel and message flows.

Send cancelledby

The @abdm/gov.in/cancelledby tag is mandatory. The HSPA needs it to select patient or doctor cancel terms.

cancel: EUA to HSPA P2P

Key field	Use
`order.id`	Send the HSPA order ID.
`order.state`	Set `CANCELLED`.
`order.fulfillment.tags.@abdm/gov.in/cancelledby`	Set `patient` or `doctor`.

POST/cancel

The EUA sends a patient cancel request to the HSPA.

cURL

curl -X POST "<provider_uri>/cancel" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "action": "cancel",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "f2a3b4c5-f951-11ec-b135-53aea776f66b",
  "timestamp": "2026-04-15T20:00:00Z"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "state": "CANCELLED",
    "fulfillment": { "tags": { "@abdm/gov.in/cancelledby": "patient" } }
  }
}
}

on_cancel: HSPA to EUA P2P

Key field	Use
`order.state`	Expect `CANCELLED`.
`order.fulfillment.tags.@abdm/gov.in/cancelledby`	Check if `patient` or `doctor` cancelled.
`order.payment.status`	Replace the local payment state.
`order.authorization`	Replace the local PIN state.

POST/on_cancel

The HSPA returns the final cancel state to the EUA.

cURL

curl -X POST "<consumer_uri>/on_cancel" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_cancel",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "a3b4c5d6-f951-11ec-b135-53aea776f66b"
},
"message": {
  "order": {
    "id": "0415-234567-8901",
    "state": "CANCELLED",
    "item": { "id": "0", "descriptor": { "code": "Consultation", "name": "Consultation" } },
    "fulfillment": {
      "id": "slot-uuid-a1",
      "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" } },
      "tags": { "@abdm/gov.in/cancelledby": "patient" }
    },
    "payment": { "type": "ON-ORDER", "status": "NOT_PAID", "params": { "amount": "500.0" } },
    "authorization": {
      "type": "PIN",
      "token": "7342",
      "valid_from": "2026-04-16T00:00:00",
      "valid_to": "2026-04-16T23:59:00",
      "status": "GENERATED"
    },
    "provider": { "id": "1" }
  }
}
}

on_message: EUA to HSPA P2P

Key field	Use
`chat.sender.person.id`	Send the patient ABHA ID.
`chat.receiver.person.id`	Send the doctor HPR ID.
`chat.content.content_value`	Send Base64 content.
`chat.content.content_type`	Set `text` or `media`.
`chat.time.timestamp`	Send the message time.

POST/on_message

The EUA sends a chat message to the HSPA.

cURL

curl -X POST "<provider_uri>/on_message" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_message",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "b4c5d6e7-42e0-11ed-b5d7-51ae9d37b46f",
  "timestamp": "2026-04-16T09:45:00Z"
},
"message": {
  "intent": {
    "chat": {
      "sender": { "person": { "id": "rahul.k001@sbx", "name": "Rahul Kumar Sharma", "gender": "M" } },
      "receiver": { "person": { "id": "priyamehra@hpr.ndhm", "name": "Dr. Priya Mehra", "gender": "F" } },
      "content": {
        "content_id": "b4c5d6e7-42e0-11ed-b5d7-51ae9d37b46f",
        "content_value": "SGVsbG8gRG9jdG9yLCBJIGhhdmUgYSBxdWVzdGlvbi4=",
        "content_type": "text"
      },
      "time": { "timestamp": "2026-04-16T09:45:00" }
    }
  }
}
}

on_message: HSPA to EUA P2P

Key field	Use
`chat.sender.person.id`	Send the doctor HPR ID.
`chat.receiver.person.id`	Send the patient ABHA ID.
`chat.content.content_value`	Send Base64 content.
`chat.content.content_mimeType`	Send it for media content.
`chat.content.hiType`	Send it for health information.

POST/on_message

The HSPA sends a chat message to the EUA.

cURL

curl -X POST "<consumer_uri>/on_message" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "on_message",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "http://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",
  "timestamp": "2022-07-05T15:24:35.481906Z",
  "provider_id": "hspa-nha",
  "provider_uri": "http://hspasbx.abdm.gov.in/api/v1",
  "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"
},
"message": {
  "intent": {
    "chat": {
      "sender": { "person": { "name": "Santosh Ramchandra Jagtap", "gender": "M", "id": "santoshjagtap@hpr.ndhm" } },
      "receiver": { "person": { "name": "Manish Pravin Kahane", "gender": "M", "id": "manishkahane1992@sbx" } },
      "content": {
        "content_id": "e616e100-42e0-11ed-b5d7-51ae9d37b46f",
        "content_value": "Base64 Encoded text",
        "content_type": "text"
      },
      "time": { "timestamp": "2022-10-03T11:32:01" }
    }
  }
}
}

Gateway support endpoints

Use the Gateway search URL

The payload for /api/v1/uhi/search matches /search. Only the URL changes.

Gateway search

Key field	Use
`Authorization`	Sign the request as the EUA.
`context.action`	Set `search`.
`context.consumer_uri`	Set the EUA callback base URI.
`message.intent`	Send the same search intent as `/search`.

POST/api/v1/uhi/search

The EUA calls the Gateway to start discovery.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"context": {
  "domain": "nic2004:85111",
  "country": "IND",
  "city": "std:011",
  "action": "search",
  "core_version": "0.7.1",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "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" },
    "item": { "descriptor": { "code": "Consultation", "name": "Consultation" } }
  }
}
}

Gateway on_search

Key field	Use
`Authorization`	Sign the request as the HSPA.
`context.action`	Set `on_search`.
`context.consumer_uri`	Keep the original EUA callback URI.
`message.catalog`	Send the provider catalog response.

POST/api/v1/uhi/on_search

The HSPA sends catalog data to the Gateway for EUA delivery.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/on_search" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_search",
  "consumer_id": "eua-nha",
  "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",
  "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" },
        "fulfillments": [ { "id": "slot-uuid-a1", "type": "Physical" } ],
        "items": [ { "id": "0", "descriptor": { "name": "Consultation" }, "fulfillment_id": "slot-uuid-a1" } ]
      }
    ]
  }
}
}

Audit endpoints

Endpoint	Key field	Use
`/api/v1/uhi/on_confirm_audit`	`action=on_confirm`	Send an exact copy of the `on_confirm` payload.
`/api/v1/uhi/on_update_audit`	`action=on_update`	Send an exact copy of the `on_update` payload.
`/api/v1/uhi/on_cancel_audit`	`action=on_cancel`	Send an exact copy of the `on_cancel` payload.
`/api/v1/uhi/on_status_audit`	`action=on_status`	Send an exact copy of the `on_status` payload.

POST/api/v1/uhi/on_confirm_audit

The HSPA sends a copy of on_confirm to the Gateway.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/on_confirm_audit" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<on_confirm-payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_confirm",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "f1a1a6b2-ece2-46a0-8229-9e8b5610afcc",
  "message_id": "f1a1a6b2-ece2-46a0-8229-9e8b5610afcc"
},
"message": {
  "order": {
    "id": "3714-330853-9384",
    "state": "CONFIRMED",
    "authorization": { "type": "PIN", "token": "3774", "status": "GENERATED" }
  }
}
}

POST/api/v1/uhi/on_update_audit

The HSPA sends a copy of on_update to the Gateway.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/on_update_audit" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<on_update-payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_update",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "e1f2a3b4-f951-11ec-b135-53aea776f66b"
},
"message": { "order": { "id": "0415-234567-8901", "state": "APPOINTMENT_STARTED" } }
}

POST/api/v1/uhi/on_cancel_audit

The HSPA sends a copy of on_cancel to the Gateway.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/on_cancel_audit" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<on_cancel-payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_cancel",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "a3b4c5d6-f951-11ec-b135-53aea776f66b"
},
"message": { "order": { "id": "0415-234567-8901", "state": "CANCELLED" } }
}

POST/api/v1/uhi/on_status_audit

The HSPA sends a copy of on_status to the Gateway.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/on_status_audit" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<on_status-payload>'

Response

{
"context": {
  "domain": "nic2004:85111",
  "action": "on_status",
  "consumer_id": "eua-nha",
  "provider_id": "hspa-nha",
  "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",
  "message_id": "c9d0e1f2-f951-11ec-b135-53aea776f66b"
},
"message": { "order": { "id": "0415-234567-8901", "state": "CONFIRMED" } }
}

Network registry lookup

Key field	Use
`subscriber_id`	Set the counterparty subscriber ID.
`type`	Set `EUA`, `HSPA`, or `gateway`.
`domain`	Set `nic2004:85111`.
`pub_key_id`	Set the key ID to look up.

POST/api/v1/networkregistry/lookup

The EUA or HSPA looks up a subscriber public key before a P2P call.

cURL

curl -X POST "https://uhigatewaysandbox.abdm.gov.in/api/v1/networkregistry/lookup" \
-H "Content-Type: application/json" \
-H "Authorization: <signed-header>" \
-d '<payload>'

Request body

{
"subscriber_id": "nha.eua",
"type": "EUA",
"domain": "nic2004:85111",
"country": "IND",
"city": "std:08752",
"pub_key_id": "nha.eua.k1"
}

Appointment states

State	Set by	Meaning
`CONFIRMED`	HSPA	The appointment has a booking and a PIN.
`APPOINTMENT_STARTED`	HSPA	The doctor starts the consultation.
`COMPLETED`	HSPA	The doctor marks the consultation complete.
`CANCELLED`	HSPA or EUA	The patient or doctor cancels the appointment.
`NO_SHOW`	HSPA	The patient does not come to the appointment.
`DOCTOR_NO_SHOW`	EUA	The doctor does not come to the appointment.

PIN state values are GENERATED, VERIFIED, NOT_VERIFIED, and HSPA_OVERRIDE.

Cancellation and override reasons

Use the reason codes as given. The EUA or HSPA can choose labels.

Patient cancel reasons

Set @abdm/gov.in/cancelledby to patient in /cancel.

#	Reason code	Label	Description
P1	`PATIENT_PERSONAL_EMERGENCY`	Personal or family emergency	The patient or family has an unexpected emergency.
P2	`PATIENT_HEALTH_IMPROVED`	Condition resolved	The patient no longer needs the consultation.
P3	`PATIENT_UNABLE_TO_VISIT_PHYSICALLY`	Cannot visit facility	The patient has a conflict or cannot visit.
P4	`DOCTOR_ASKED_TO_CANCEL`	Doctor requested cancel	The doctor asked the patient to cancel.
P5	`PATIENT_BOOKED_IN_ERROR`	Wrong appointment	The patient selected the wrong doctor, speciality, date, or time.
P6	`PATIENT_SEEKING_ALTERNATIVE`	Alternative provider	The patient chose a different provider.
P7	`PATIENT_OTHER`	Other	Capture mandatory free text.

Doctor or facility cancel reasons

Set @abdm/gov.in/cancelledby to doctor in /on_cancel.

#	Reason code	Label	Description
D1	`DOCTOR_PERSONAL_EMERGENCY`	Doctor emergency	The doctor has unplanned leave or a medical emergency.
D2	`DOCTOR_UNAVAILABLE`	Doctor unavailable	The doctor has surgery, an urgent appointment, an emergency, or high patient load.
D3	`DOCTOR_SCHEDULE_CHANGE`	Schedule change	The clinic or provider changed the doctor session.
D4	`FACILITY_CLOSURE`	Facility closure	The facility closed due to a holiday or infrastructure issue.
D5	`TECHNICAL_SYSTEM_ISSUE`	Technical issue	The HSPA platform has downtime or a failure.
D6	`DOCTOR_OTHER`	Other	Capture mandatory free text.

HSPA PIN override reasons

Use these codes when facility staff bypass normal PIN verification.

#	Reason code	Label	Scenario
O1	`OVERRIDE_EMERGENCY_CONSULTATION`	Medical emergency	The patient arrives in acute distress.
O2	`OVERRIDE_PIN_TECH_FAILURE`	PIN technical failure	The patient app cannot show the PIN, and staff verify identity.
O3	`OVERRIDE_PIN_DELIVERY_FAILURE`	PIN not received	The patient has a booking reference but did not receive the PIN.
O4	`OVERRIDE_VULNERABLE_PATIENT`	Vulnerable patient	The patient cannot use the EUA to retrieve the PIN.
O5	`OVERRIDE_EUA_OUTAGE`	EUA outage	The EUA platform is down or not reachable.
O6	`OVERRIDE_MISMATCH`	PIN mismatch	HSPA cannot validate the patient PIN after 3 attempts.
O6	`OVERRIDE_OTHER`	Other	Capture mandatory free text.

Known constraints

Constraint	Detail
Pay-on-visit only	Use `ON-ORDER` for Phase 1 payment on visit.
No refund flow	The current flow does not include online refund.
Phase 2 status	Online payment and refund are in ideation.

Resources

Header Generation Utility

Use this NHA utility to generate Ed25519 keys and request headers.

Gateway Swagger

Use the Swagger for the full UHI Gateway API field list.

Sources

UHI Physical Consultation v2.0 — Onboarding Document (June 2026)

PreviousOnboarding Next PM-JAY Hospital Discovery