ABDM API — Documents

Document endpoints are POST and authenticated (Authorization: Bearer <idToken>). Each creates a FHIR Composition and pushes it to ABDM. Each returns a CompositionRes object (a composition FHIR resource). All use "patientNeeds" — at least one of abhaAddress (string) or patientId (number); omitting both yields 400 VALIDATION_ERROR.

The five document endpoints share these error codes (plus each endpoint's own extras):

INVALID_DOCTOR_GCP_FHIR_ID (400) · PATIENT_NOT_FOUND (404) · ENCOUNTER_NOT_FOUND (404) · NO_ACTIVE_ENCOUNTER (409) · ABDM_GATEWAY_ERROR (502) · LINK_TOKEN_MISSING (502) · LINK_TOKEN_RATE_LIMITED (429)

Encounter resolution

Every document is filed against an encounter (the ABDM care-context reference). Each of the five endpoints accepts an optional encounterId; resolution works the same way for all of them:

1. encounterId supplied — that encounter is used. It must belong to the patient and to your organization, otherwise 404 ENCOUNTER_NOT_FOUND.
2. encounterId omitted — the patient's open encounter is used (status in-progress, arrived, planned, triaged).
3. No open encounter — the patient's most recent encounter is used, whatever its status (including finished) — so a discharged patient's documents still upload.
4. No encounter at all — 409 NO_ACTIVE_ENCOUNTER. Create a visit with /opd_patient or /admit_patient before pushing a document.

File uploads

The four JSON document endpoints — /discharge_summary, /diagnostic_report, /op_consultation, /procedure_ot_notes — accept text/HTML only via their text / content fields. They cannot accept file attachments (no multipart upload).

Only /health_document accepts file uploads. It accepts PDF, JPEG or PNG files up to 5 MB each, across page1–page4, with a PDF uploaded on its own — a PDF cannot be combined with images. A file's type is determined from the file's own bytes, not from the Content-Type you send for that part, so a renamed or mislabelled file is rejected rather than silently stored as something else. Scanned PDFs can be sent directly — converting to images is no longer required.

/discharge_summary — POST (auth)

Creates a DischargeSummary composition and pushes it to ABDM.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "abhaAddress": "savitribilagi@sbx",
  "text": "<div>Cough with APD</div><div>cough</div><div>BP 140/80 PR 87/min RR 20/min</div>",
  "doctorDetails": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "status": "final",
  "date": "2023-05-08T19:21:23.918Z"
}

Example response

{
  "composition": {
    "id": "e721069a-cc8c-4e5e-a437-b4cfcaee11a4",
    "resourceType": "Composition",
    "status": "final",
    "title": "DischargeSummary",
    "date": "2023-05-08T19:21:23.918Z",
    "subject": { "reference": "Patient/9b4ec056-991d-4237-b1fd-a65770349610" }
  }
}

Error codes

• Shared document codes + shared auth codes.
• ENCOUNTER_NOT_FOUND (404) — a supplied encounterId does not belong to this patient and org.
• NO_ACTIVE_ENCOUNTER (409) — the patient has no encounter at all; create a visit first.

/diagnostic_report — POST (auth)

Creates a DiagnosticReport composition and pushes it to ABDM.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "abhaAddress": "savitribilagi@sbx",
  "performer": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "testName": "CT Abdomen",
  "category": "Radiology",
  "text": "<div>Ultrasound Report ...</div>",
  "status": "final",
  "conclusion": "Normal Study"
}

Example response

Returns a CompositionRes object.

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400) — validates performer and requester.
• PATIENT_NOT_FOUND (404) · ENCOUNTER_NOT_FOUND (404) · NO_ACTIVE_ENCOUNTER (409)
• ABDM_GATEWAY_ERROR (502) · LINK_TOKEN_MISSING (502) · LINK_TOKEN_RATE_LIMITED (429)
• shared codes

/op_consultation — POST (auth)

Creates an OP Consultation composition and pushes it to ABDM.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

{
  "abhaAddress": "savitribilagi@sbx",
  "doctorDetails": [
    { "doctorName": "Dr Umesh Bilagi", "doctorGcpId": "cf4a6ab1-3f32-4b92-adc5-89489da6ca14" }
  ],
  "date": "2023-05-08T19:21:23.918Z",
  "status": "final",
  "chiefComplaints": "Cough and fever",
  "medicines": [
    { "drug": "Paracetamol", "frequency": "BD", "instruction": "After food", "duration": "5 days", "route": "Oral" }
  ]
}

Example response

Returns a CompositionRes object.

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400)
• PATIENT_NOT_FOUND (404) · ENCOUNTER_NOT_FOUND (404) · NO_ACTIVE_ENCOUNTER (409)
• ABDM_GATEWAY_ERROR (502) · LINK_TOKEN_MISSING (502) · LINK_TOKEN_RATE_LIMITED (429)
• shared codes

/procedure_ot_notes — POST (auth)

Creates a procedure / OT-notes composition and pushes it to ABDM.

Request fields

* At least one of abhaAddress / patientId is required.

Example request

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

Example response

Returns a CompositionRes object.

Error codes

• INVALID_DOCTOR_GCP_FHIR_ID (400)
• PATIENT_NOT_FOUND (404) · ENCOUNTER_NOT_FOUND (404) · NO_ACTIVE_ENCOUNTER (409)
• ABDM_GATEWAY_ERROR (502) · LINK_TOKEN_MISSING (502) · LINK_TOKEN_RATE_LIMITED (429)
• shared codes

/health_document — POST (multipart/form-data, auth)

Uploads a scanned health document (PDF, JPEG or PNG) and creates a HealthDocumentRecord composition. Each file must be under 5 MB.

Request fields (form fields)

* At least one of abhaAddress / patientId is required.

Files

If one of page1–page4 is a PDF, it must be the only file in the request. Send the request as multipart/form-data using your client's multipart mode — do not set a Content-Type header by hand, or the multipart boundary is lost and the request is rejected.

Example response

Returns a CompositionRes object, plus:

Error codes

• INVALID_REQUEST_METHOD (400) — non-POST method.
• DOCTOR_DETAILS_REQUIRED (400) — doctorDetails form field missing.
• VALIDATION_ERROR (400) — invalid form fields; unsupported file type; no file sent; a PDF combined with images.
• VALIDATION_ERROR (413) — a file exceeds the 5 MB limit.
• INVALID_DOCTOR_GCP_FHIR_ID (400)
• PATIENT_NOT_FOUND (404) · ENCOUNTER_NOT_FOUND (404) · NO_ACTIVE_ENCOUNTER (409)
• ABDM_GATEWAY_ERROR (502) · LINK_TOKEN_MISSING (502) · LINK_TOKEN_RATE_LIMITED (429)
• shared codes