ABDM API — Patient Visits

Visit endpoints are authenticated (Authorization: Bearer <idToken>). opd_patient and admit_patient are POST; discharge_patient is PUT.

Each route accepts "patientNeeds" — at least one of abhaAddress (string) or patientId (number). Omitting both yields 400 VALIDATION_ERROR with the message "Either abhaAddress or patientId is required".

Send exactly one identifier. When both are supplied the lookup precedence is undefined — a bad abhaAddress (e.g. an unresolved placeholder) can mask a valid patientId and cause PATIENT_NOT_FOUND. See Error Handling → Troubleshooting: PATIENT_NOT_FOUND.

Visit lifecycle — create only for a new visit

Creating a visit (/opd_patient or /admit_patient) automatically closes any currently open encounter for that patient (sets its status to finished). You do not need to close the previous visit manually before starting the next one.

Call these endpoints only when a genuinely new visit starts. Repeated calls for the same ongoing visit create duplicate encounters. To close an encounter explicitly, use /discharge_patient.

A newly created encounter is in-progress and has period.start only — period.end is set only on discharge.

OPD / IP numbers

Every visit is assigned a number automatically from the organization's own sequence (the same one used by visits created inside the HMS). The number is org-scoped, not global, and the caller does not send it.

It is stored on the encounter as an extension and can be read by the HMS:

"extension": [{ "url": "https://nicehms.com/OPD", "valueString": "42" }]

/admit_patient uses https://nicehms.com/IPD. valueString is always a string. Visits created before this was introduced have no number.

/opd_patient — POST (auth)

Creates an OPD (outpatient) visit and care context within the ABDM framework. Before sending, check whether there is already an active OPD visit.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "date": "2023-05-08T19:21:23.918Z",
  "doctorDetails": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "abhaAddress": "savitribilagi@sbx"
}

Example response

Returns an EncounterRes object — an encounter FHIR resource with id, status (in-progress), subject.reference, participant, and period.

{
  "encounter": {
    "id": "65cb5b6a-f08e-4e46-a826-67e117573d71",
    "status": "in-progress",
    "class": { "code": "AMB", "display": "ambulatory", "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode" },
    "subject": { "reference": "Patient/9b4ec056-991d-4237-b1fd-a65770349610" },
    "period": { "start": "2023-05-08T19:21:23.918Z" }
  }
}

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400) — a doctorGcpId is not a valid Practitioner.
• PATIENT_NOT_FOUND (404)
• shared codes

/admit_patient — POST (auth)

Creates an IPD (inpatient) admission visit and care context within ABDM. Before sending, check whether there is already an active IPD visit.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "doa": "2023-05-10T19:21:23.918Z",
  "doctorDetails": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "patientId": 236
}

Example response

Returns an EncounterRes object (same shape as /opd_patient).

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400)
• PATIENT_NOT_FOUND (404)
• shared codes

/discharge_patient — PUT (auth)

Discharges a patient by setting the discharge date and closing the encounter. Call this before sending the discharge summary document, as it updates the discharge date.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "encounterId": "21ba04cd-d922-4412-bfdc-c0293e638f1d",
  "dod": "2023-05-11T19:21:23.918Z",
  "doctorDetails": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "patientId": 236
}

Example response

Returns an EncounterRes object (with status updated and period.end set).

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400)
• PATIENT_NOT_FOUND (404)
• ENCOUNTER_NOT_FOUND (404) — the supplied encounterId was not found.
• shared codes