---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/patient/{patientId}/deceased"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/deceased/agents.md"
kind: "endpoints"
methods: [GET, POST, PUT, PATCH, DELETE]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/deceased/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/deceased/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/deceased/use-case.md"
source_version: "43d07c0335624b7661c2872315a5f184e8c3d832"
extractor_model: "gpt-4o-2024-08-06"
extractor_prompt_version: "2026-08-13.v1"
reconciler_model: "claude-sonnet-4-6"
reconciler_prompt_version: "2026-08-13.v1"
generated_at: "2026-08-27T01:13:03.949984+00:00"
---

# /v3/patient/{patientId}/deceased

**URL**: https://demo.1health.io/api/v3/patient/{patientId}/deceased

APIs for marking a patient deceased and managing the structured death record (date, time, cause, manner, place of death, certifier). Reversal is expressed via DELETE; corrections via PUT/PATCH.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/deceased | GET | Get a patient's deceased record |
| /v3/patient/{patientId}/deceased | POST | Mark a patient deceased |
| /v3/patient/{patientId}/deceased | PUT | Fully update a patient's deceased record |
| /v3/patient/{patientId}/deceased | PATCH | Partially update a patient's deceased record |
| /v3/patient/{patientId}/deceased | DELETE | Reverse a patient's deceased record |

---

## GET /v3/patient/{patientId}/deceased

Get a patient's deceased record

### Overview

**Overview**: Returns the patient's deceased record.

**Important Notes**:
- Requires authentication
- Returns 404 if the patient is not marked deceased

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Responses

#### 200 OK

Deceased record found.

**DTO**: `PatientDeceasedResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value",
  "createdAt": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Deceased record ID. |
| patientId | Long | No | ID of the patient this record is for. |
| deceasedDate | string | No | Date of death (YYYY-MM-DD). |
| deceasedTime | String | Yes | Time of death (HH:MM, 24-hour UTC). |
| cause | String | Yes | Cause of death — ICD-10 code or freeform text. |
| manner | String | Yes | Manner of death. |
| placeOfDeath | String | Yes | Facility name or location description. |
| certifierId | String | Yes | NPI of the certifying provider. |
| notes | String | Yes | Additional narrative notes. |
| createdAt | string | No | When the record was created (UTC). |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found, or patient is not marked deceased.

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient/1001/deceased" \
  -H "Authorization: Bearer $TOKEN"
```

## POST /v3/patient/{patientId}/deceased

Mark a patient deceased

### Overview

**Overview**: Creates the patient's deceased record and sets the deceased flag that blocks new appointments and orders. Returns a server-assigned `id`.

**Behavior & Use Cases**:
- `deceasedDate` is required (YYYY-MM-DD); it cannot be in the future or before the patient's date of birth
- `manner`, when provided, must be one of: Natural, Accident, Homicide, Suicide, Undetermined, Pending
- Not idempotent — returns 409 if the patient is already marked deceased (use PUT/PATCH to correct)

**Important Notes**:
- Requires authentication

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Request Body

**Content-Type**: `application/json` · **DTO**: `PatientDeceasedRequestDTO`

```json
{
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| deceasedDate | string | Yes | format: date | Date of death (YYYY-MM-DD). |
| deceasedTime | string | No |  | Time of death (HH:MM, 24-hour UTC). |
| cause | string | No |  | Cause of death — ICD-10 code or freeform text. |
| manner | string | No |  | Manner of death — one of: Natural, Accident, Homicide, Suicide, Undetermined, Pending. |
| placeOfDeath | string | No |  | Facility name or location description. |
| certifierId | string | No |  | NPI of the certifying provider. |
| notes | string | No |  | Additional narrative notes. |

### Responses

#### 201 Created

Deceased record created successfully.

**DTO**: `PatientDeceasedResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value",
  "createdAt": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Deceased record ID. |
| patientId | Long | No | ID of the patient this record is for. |
| deceasedDate | string | No | Date of death (YYYY-MM-DD). |
| deceasedTime | String | Yes | Time of death (HH:MM, 24-hour UTC). |
| cause | String | Yes | Cause of death — ICD-10 code or freeform text. |
| manner | String | Yes | Manner of death. |
| placeOfDeath | String | Yes | Facility name or location description. |
| certifierId | String | Yes | NPI of the certifying provider. |
| notes | String | Yes | Additional narrative notes. |
| createdAt | string | No | When the record was created (UTC). |

#### 400 Bad Request

Invalid request. Possible causes: • Missing required field (`deceasedDate`) • Invalid `deceasedDate` format, in the future, or before date of birth • Invalid `manner` • Invalid `deceasedTime` format (expected HH:MM, 24-hour)

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

#### 409 Conflict

Patient is already marked deceased.

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient/1001/deceased" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"deceasedDate": "example-value", "deceasedTime": "example-value", "cause": "example-value", "manner": "example-value", "placeOfDeath": "example-value", "certifierId": "example-value", "notes": "example-value"}'
```

## PUT /v3/patient/{patientId}/deceased

Fully update a patient's deceased record

### Overview

**Overview**: Replaces the deceased record. Use when correcting multiple fields at once.

**Behavior & Use Cases**:
- `deceasedDate` is required
- Optional fields that are omitted (or sent as their default value, e.g. `n/a` for text fields) are reset to their defaults
- Does not reverse the record — the patient stays marked deceased

**Important Notes**:
- Requires authentication
- Returns 404 if the patient is not marked deceased

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Request Body

**Content-Type**: `application/json` · **DTO**: `PatientDeceasedRequestDTO`

```json
{
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| deceasedDate | string | Yes | format: date | Date of death (YYYY-MM-DD). |
| deceasedTime | string | No |  | Time of death (HH:MM, 24-hour UTC). |
| cause | string | No |  | Cause of death — ICD-10 code or freeform text. |
| manner | string | No |  | Manner of death — one of: Natural, Accident, Homicide, Suicide, Undetermined, Pending. |
| placeOfDeath | string | No |  | Facility name or location description. |
| certifierId | string | No |  | NPI of the certifying provider. |
| notes | string | No |  | Additional narrative notes. |

### Responses

#### 200 OK

Deceased record updated successfully.

**DTO**: `PatientDeceasedResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value",
  "createdAt": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Deceased record ID. |
| patientId | Long | No | ID of the patient this record is for. |
| deceasedDate | string | No | Date of death (YYYY-MM-DD). |
| deceasedTime | String | Yes | Time of death (HH:MM, 24-hour UTC). |
| cause | String | Yes | Cause of death — ICD-10 code or freeform text. |
| manner | String | Yes | Manner of death. |
| placeOfDeath | String | Yes | Facility name or location description. |
| certifierId | String | Yes | NPI of the certifying provider. |
| notes | String | Yes | Additional narrative notes. |
| createdAt | string | No | When the record was created (UTC). |

#### 400 Bad Request

Invalid request. Possible causes: • Missing required field (`deceasedDate`) • Invalid `deceasedDate` format, in the future, or before date of birth • Invalid `manner` • Invalid `deceasedTime` format (expected HH:MM, 24-hour)

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found, or patient is not marked deceased.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001/deceased" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"deceasedDate": "example-value", "deceasedTime": "example-value", "cause": "example-value", "manner": "example-value", "placeOfDeath": "example-value", "certifierId": "example-value", "notes": "example-value"}'
```

## PATCH /v3/patient/{patientId}/deceased

Partially update a patient's deceased record

### Overview

**Overview**: Updates only the fields provided in the request body. Use to correct a wrong date or other specific fields without reversing the record.

**Behavior & Use Cases**:
- Omitted fields are left unchanged
- To clear an optional field, send its default value (`n/a` for text fields)
- `deceasedDate` is required and cannot be cleared
- Does not reverse the record — the patient stays marked deceased
- The response echoes only the fields changed by this request (plus `id`, `patientId` and `createdAt`); unchanged fields are omitted

**Important Notes**:
- Requires authentication
- Returns 404 if the patient is not marked deceased

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Request Body

**Content-Type**: `application/json` · **DTO**: `PatientDeceasedRequestDTO`

```json
{
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| deceasedDate | string | Yes | format: date | Date of death (YYYY-MM-DD). |
| deceasedTime | string | No |  | Time of death (HH:MM, 24-hour UTC). |
| cause | string | No |  | Cause of death — ICD-10 code or freeform text. |
| manner | string | No |  | Manner of death — one of: Natural, Accident, Homicide, Suicide, Undetermined, Pending. |
| placeOfDeath | string | No |  | Facility name or location description. |
| certifierId | string | No |  | NPI of the certifying provider. |
| notes | string | No |  | Additional narrative notes. |

### Responses

#### 200 OK

Deceased record partially updated successfully.

**DTO**: `PatientDeceasedResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "deceasedDate": "example-value",
  "deceasedTime": "example-value",
  "cause": "example-value",
  "manner": "example-value",
  "placeOfDeath": "example-value",
  "certifierId": "example-value",
  "notes": "example-value",
  "createdAt": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Deceased record ID. |
| patientId | Long | No | ID of the patient this record is for. |
| deceasedDate | string | No | Date of death (YYYY-MM-DD). |
| deceasedTime | String | Yes | Time of death (HH:MM, 24-hour UTC). |
| cause | String | Yes | Cause of death — ICD-10 code or freeform text. |
| manner | String | Yes | Manner of death. |
| placeOfDeath | String | Yes | Facility name or location description. |
| certifierId | String | Yes | NPI of the certifying provider. |
| notes | String | Yes | Additional narrative notes. |
| createdAt | string | No | When the record was created (UTC). |

#### 400 Bad Request

Invalid request. Possible causes: • Invalid `deceasedDate` format, in the future, or before date of birth • Invalid `manner` • Invalid `deceasedTime` format (expected HH:MM, 24-hour)

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found, or patient is not marked deceased.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/deceased" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"deceasedDate": "example-value", "deceasedTime": "example-value", "cause": "example-value", "manner": "example-value", "placeOfDeath": "example-value", "certifierId": "example-value", "notes": "example-value"}'
```

## DELETE /v3/patient/{patientId}/deceased

Reverse a patient's deceased record

### Overview

**Overview**: Reverses the record: the patient is no longer marked deceased. The original deceased record and this reversal are preserved in History (the record is soft-deleted, not removed).

**Important Notes**:
- Requires authentication
- Idempotent — reversing an already-reversed (or never-set) record returns 200

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Responses

#### 200 OK

Deceased record reversed successfully.

**DTO**: `PatientDeceasedDeleteResponseDTO`

```json
{
  "id": 1001,
  "reversed": true,
  "reversedAt": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the reversed deceased record. Omitted when the patient was not marked deceased. |
| reversed | boolean | No | Always true — the patient is no longer marked deceased. |
| reversedAt | string | No | When the reversal happened (UTC). |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

### Example

```bash
curl -X DELETE "https://demo.1health.io/api/v3/patient/1001/deceased" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Navigation
Parent: https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md · Site guide: https://agents.1health.io/public/demo/api/agents.md