---
title: "ABDM API — Documents"
description: "Nice HMS ABDM document endpoints that create FHIR compositions and push them to ABDM: discharge_summary, diagnostic_report, op_consultation, procedure_ot_notes, and health_document (multipart)."
date: 2026-08-26
lastModified: 2026-08-26
category: "developer"
author: "Dr. Umesh Bilagi"
beta: true
---

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) · `ABDM_GATEWAY_ERROR` (502) · `LINK_TOKEN_MISSING` (502)

---

## `/discharge_summary` — POST (auth)

Creates a DischargeSummary composition and pushes it to ABDM.

### Request fields

| Name | Type | Required | Description |
|---|---|---|---|
| `doctorDetails` | array | Yes | Array of `{ doctorName, doctorGcpId }`, min 1. |
| `text` | string | Yes | Summary content (HTML allowed). |
| `status` | string | Yes | e.g. `"final"` or `"draft"`. |
| `date` | string | Yes | ISO date. |
| `compositionId` | string | No | Optional composition id. |
| `abhaAddress` | string | —* | Patient's ABHA address. |
| `patientId` | number | —* | Nice HMS patient id. |

\* At least one of `abhaAddress` / `patientId` is required.

### Example request

```json
{
  "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

```json
{
  "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.

---

## `/diagnostic_report` — POST (auth)

Creates a DiagnosticReport composition and pushes it to ABDM.

### Request fields

| Name | Type | Required | Description |
|---|---|---|---|
| `performer` | array | Yes | Array of `{ doctorName, doctorGcpId }`, min 1. The performer is who signs the report. |
| `testName` | string | Yes | Non-empty, e.g. `"CT Abdomen"`. |
| `category` | string | Yes | `"Hematology"` \| `"Biochemistry"` \| `"Microbiology"` \| `"Radiology"` \| `"Others"`. |
| `text` | string | Yes | Non-empty report content (HTML allowed). |
| `status` | string | Yes | e.g. `"final"` or `"draft"`. |
| `requester` | object | No | `{ doctorName, doctorGcpId }`. If omitted, the requester is assumed to be the patient. |
| `conclusion` | string | No | e.g. `"Normal Study"`. |
| `compositionId` | string | No | Optional. |
| `date` | string | No | ISO date; defaults to the request timestamp when omitted. |
| `abhaAddress` | string | —* | Patient's ABHA address. |
| `patientId` | number | —* | Nice HMS patient id. |

\* At least one of `abhaAddress` / `patientId` is required.

### Example request

```json
{
  "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)
- `ABDM_GATEWAY_ERROR` (502) · `LINK_TOKEN_MISSING` (502)
- shared codes

---

## `/op_consultation` — POST (auth)

Creates an OP Consultation composition and pushes it to ABDM.

### Request fields

| Name | Type | Required | Description |
|---|---|---|---|
| `doctorDetails` | array | Yes | Array of `{ doctorName, doctorGcpId }`, min 1. |
| `date` | string | Yes | ISO date of the consultation. |
| `status` | string | Yes | Current status of the consultation. |
| `chiefComplaints` | string | No | Primary complaints reported by the patient. |
| `medicalHistory` | string | No | Patient's past medical history. |
| `physicalExamination` | string | No | Findings from the physical examination. |
| `medicines` | array | No | Array of `{ drug, frequency, instruction, duration, route }`. |
| `opdProcedure` | object | No | `{ procedureName, procedureDescription, date? }`. |
| `followUp` | object | No | `{ startDate, endDate?, comment }`. |
| `compositionId` | string | No | Optional. |
| `abhaAddress` | string | —* | Patient's ABHA address. |
| `patientId` | number | —* | Nice HMS patient id. |

\* At least one of `abhaAddress` / `patientId` is required.

### Example request

```json
{
  "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)
- `ABDM_GATEWAY_ERROR` (502) · `LINK_TOKEN_MISSING` (502)
- shared codes

---

## `/procedure_ot_notes` — POST (auth)

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

### Request fields

| Name | Type | Required | Description |
|---|---|---|---|
| `doctorDetails` | array | Yes | Array of `{ doctorName, doctorGcpId }`, min 1. |
| `date` | string | Yes | ISO date of the procedure. |
| `status` | string | Yes | Current status of the procedure. |
| `opdProcedure` | object | No | `{ procedureName, procedureDescription, date? }`. |
| `followUp` | object | No | `{ startDate, endDate?, comment }`. |
| `compositionId` | string | No | Optional. |
| `abhaAddress` | string | —* | Patient's ABHA address. |
| `patientId` | number | —* | Nice HMS patient id. |

\* At least one of `abhaAddress` / `patientId` is required.

### Example request

```json
{
  "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)
- `ABDM_GATEWAY_ERROR` (502) · `LINK_TOKEN_MISSING` (502)
- shared codes

---

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

Uploads scanned health document images and creates a HealthDocumentRecord composition.
Payload size should be under 2 MB.

### Request fields (form fields)

| Name | Type | Required | Description |
|---|---|---|---|
| `doctorDetails` | string | Yes | **JSON string**, e.g. `"[{\"doctorName\":\"Dr Umesh\",\"doctorGcpId\":\"...\"}]"`. |
| `text` | string | Yes | Title, e.g. `"Prescription"` or `"Lab report"`. |
| `status` | string | Yes | e.g. `"final"` or `"draft"`. |
| `date` | string | No | ISO date. |
| `compositionId` | string | No | Optional. |
| `abhaAddress` | string | —* | Patient's ABHA address. |
| `patientId` | number | —* | Nice HMS patient id. |

\* At least one of `abhaAddress` / `patientId` is required.

### Files

| Name | Required | Description |
|---|---|---|
| `page1` | Yes | Image (JPEG), ≤ 2 MB. |
| `page2` | No | Optional image. |
| `page3` | No | Optional image. |
| `page4` | No | Optional image. |

### Example response

Returns a `CompositionRes` object.

### Error codes

- `INVALID_REQUEST_METHOD` (400) — non-POST method.
- `DOCTOR_DETAILS_REQUIRED` (400) — `doctorDetails` form field missing.
- `VALIDATION_ERROR` (400) — invalid form fields.
- `INVALID_DOCTOR_GCP_FHIR_ID` (400)
- `PATIENT_NOT_FOUND` (404) · `ENCOUNTER_NOT_FOUND` (404)
- `ABDM_GATEWAY_ERROR` (502) · `LINK_TOKEN_MISSING` (502)
- shared codes