Patient Vault v3 API

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

---

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.

Path Parameters

Responses

200 OK

Deceased record found.

DTO: PatientDeceasedResponseDTO

{
  "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"
}

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found, or patient is not marked deceased.

Example

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.

Path Parameters

Request Body

Content-Type: application/json · DTO: PatientDeceasedRequestDTO

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

Responses

201 Created

Deceased record created successfully.

DTO: PatientDeceasedResponseDTO

{
  "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"
}

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

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.

Path Parameters

Request Body

Content-Type: application/json · DTO: PatientDeceasedRequestDTO

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

Responses

200 OK

Deceased record updated successfully.

DTO: PatientDeceasedResponseDTO

{
  "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"
}

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

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.

Path Parameters

Request Body

Content-Type: application/json · DTO: PatientDeceasedRequestDTO

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

Responses

200 OK

Deceased record partially updated successfully.

DTO: PatientDeceasedResponseDTO

{
  "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"
}

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

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.

Path Parameters

Responses

200 OK

Deceased record reversed successfully.

DTO: PatientDeceasedDeleteResponseDTO

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

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found.

Example

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