---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/patient"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/patient/agents.md"
kind: "endpoints"
methods: [GET, POST, PUT, PATCH, DELETE]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/patient/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/patient/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/patient/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

**URL**: https://demo.1health.io/api/v3/patient

REST API for managing patient demographic records in the Patient Vault. Provides create, full update, partial update, and delete operations for patient demographic information including name, date of birth, gender, race, ethnicity, and SSN.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient | GET | List patient records |
| /v3/patient | POST | Create a patient record |
| /v3/patient/{id} | GET | Get a patient record by ID |
| /v3/patient/{id} | PUT | Fully update a patient record |
| /v3/patient/{id} | PATCH | Partially update a patient record |
| /v3/patient/{id} | DELETE | Delete a patient record |

---

## GET /v3/patient

List patient records

### Overview

Returns a paginated list of patient demographic records for the current tenant's organization. Each entry carries the same demographic fields as the single-patient endpoint. Only patients of the caller's organization are returned. Soft-deleted patients are excluded. Results are returned page by page; use page and size to navigate. Returns 200 with an empty list when the organization has no patients — not a 404. Requires authentication. page is zero-based and defaults to 0. size defaults to 50.

### Authorization

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

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| page | int | No | 0 | Zero-based page index to retrieve. Defaults to 0 when omitted. |
| size | int | No | 50 | Number of records per page. Defaults to 50 when omitted. |

### Responses

#### 200 OK

Paginated list of patient records (possibly empty).

**DTO**: `Page<PatientResponseDTO>`

```json
{
  "data": [
    {}
  ],
  "pageNumber": 1,
  "pageSize": 1,
  "offset": 1001,
  "emptyPage": true,
  "firstPage": true,
  "lastPage": true,
  "numberOfElements": 1001,
  "totalElements": 1001,
  "totalPages": 1
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| data | List<PatientResponseDTO> | No |  |
| pageNumber | int | No |  |
| pageSize | int | No |  |
| offset | long | No |  |
| emptyPage | boolean | No |  |
| firstPage | boolean | No |  |
| lastPage | boolean | No |  |
| numberOfElements | long | No |  |
| totalElements | long | No |  |
| totalPages | int | No |  |

#### 401 Unauthorized

Not authenticated — valid session required.

### Example

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

## POST /v3/patient

Create a patient record

### Overview

Creates a new patient demographic record in the Patient Vault. Required fields are first name, last name, and date of birth. Enum fields (gender, race, ethnicity) default to Unknown if not provided. The Patient Vault never decides whether two records are the same person, and never blocks or merges based on similarity. Every call creates a new, distinct patient — even when an identical record (same firstName, lastName, and dob, and even the same last4Ssn, race, and ethnicity) already exists in the tenant. No SSN, race, or ethnicity is ever required to disambiguate. Use the patient find/match API to detect and resolve potential duplicates yourself. If last4Ssn is provided, it is stored in masked format (e.g. ***-**-1234) — the full SSN is never stored or returned. All value-list fields (gender, race, ethnicity) are validated against their allowed values. Requires authentication. Date fields must be in YYYY-MM-DD format. Date of birth cannot be in the future. Deceased status is read-only here — manage it via the /v3/patient/{patientId}/deceased endpoints.

### Authorization

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

### Request Body

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

```json
{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| firstName | string | Yes | Cannot be cleared. | Legal first name. |
| lastName | string | Yes | Cannot be cleared. | Legal last name / surname. |
| middleName | string | No | Optional; clear with `n/a`. | Middle name or initial. |
| dob | string | Yes | Cannot be cleared. | Date of birth in YYYY-MM-DD format. |
| gender | string | No | Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown. | Administrative sex. |
| genderIdentity | string | No | Optional; clear with `n/a`. | Self-reported gender identity (freeform or coded). |
| sexAtBirth | string | No | Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown. | Biological sex at birth. |
| race | string | No | Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown. | OMB race category. |
| ethnicity | string | No | Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown. | OMB ethnicity category. |
| preferredLanguage | string | No | Optional; clear with `n/a`. | Free form language name. |
| last4Ssn | string | No | Must be exactly 4 numeric digits. Cannot be cleared. | Last 4 digits of Social Security Number. |

### Responses

#### 200 OK

Patient record created successfully.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Person instance ID. |
| firstName | String | No | Legal first name. |
| lastName | String | No | Legal last name / surname. |
| middleName | String | Yes | Middle name or initial. |
| dob | String | No | Date of birth (YYYY-MM-DD). |
| gender | String | Yes | Administrative sex. |
| genderIdentity | String | Yes | Self-reported gender identity. |
| sexAtBirth | String | Yes | Biological sex at birth. |
| race | String | Yes | OMB race category. |
| ethnicity | String | Yes | OMB ethnicity category. |
| preferredLanguage | String | Yes | Preferred language. |
| ssnPreview | String | Yes | Masked SSN preview. Only last 4 digits shown. |
| updatedBy | String | Yes | User who last updated the patient record. |
| updated | LocalDateTime | Yes | Timestamp of the last update. |

#### 400 Bad Request

Invalid request. Possible causes: A required field (firstName, lastName, dob) is missing, blank, or set to n/a; Invalid value for gender, race, or ethnicity; Invalid date format for dob; Date of birth is in the future; last4Ssn is not exactly 4 digits

#### 401 Unauthorized

Not authenticated — valid session required.

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'
```

## GET /v3/patient/{id}

Get a patient record by ID

### Overview

Returns the demographic record of a single patient by ID. The response carries the same fields as each entry in the patient list. Returns the patient's demographics including name, date of birth, gender, race, ethnicity, preferred language, and masked SSN preview. The full SSN is never returned — only the masked preview (e.g. ***-**-1234). Requires authentication. Idempotent — repeated calls return the same result. Returns 404 if the patient does not exist in the current tenant.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | Long | Yes | The ID of the patient record to retrieve. |

### Responses

#### 200 OK

Patient record found.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Person instance ID. |
| firstName | String | No | Legal first name. |
| lastName | String | No | Legal last name / surname. |
| middleName | String | Yes | Middle name or initial. |
| dob | String | No | Date of birth (YYYY-MM-DD). |
| gender | String | Yes | Administrative sex. |
| genderIdentity | String | Yes | Self-reported gender identity. |
| sexAtBirth | String | Yes | Biological sex at birth. |
| race | String | Yes | OMB race category. |
| ethnicity | String | Yes | OMB ethnicity category. |
| preferredLanguage | String | Yes | Preferred language. |
| ssnPreview | String | Yes | Masked SSN preview. Only last 4 digits shown. |
| updatedBy | String | Yes | User who last updated the patient record. |
| updated | LocalDateTime | Yes | Timestamp of the last update. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

### Example

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

## PUT /v3/patient/{id}

Fully update a patient record

### Overview

Replaces all demographic fields of an existing patient record. All required fields must be provided. Optional fields omitted from the request will be cleared. All required fields (firstName, lastName, dob) must be present. Optional fields not included in the request body are set to null. Use PATCH instead if you only want to update specific fields without clearing others. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | Long | Yes | The ID of the patient record to update. |

### Request Body

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

```json
{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| firstName | string | Yes | Cannot be cleared. | Legal first name. |
| lastName | string | Yes | Cannot be cleared. | Legal last name / surname. |
| middleName | string | No | Optional; clear with `n/a`. | Middle name or initial. |
| dob | string | Yes | Cannot be cleared. | Date of birth in YYYY-MM-DD format. |
| gender | string | No | Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown. | Administrative sex. |
| genderIdentity | string | No | Optional; clear with `n/a`. | Self-reported gender identity (freeform or coded). |
| sexAtBirth | string | No | Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown. | Biological sex at birth. |
| race | string | No | Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown. | OMB race category. |
| ethnicity | string | No | Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown. | OMB ethnicity category. |
| preferredLanguage | string | No | Optional; clear with `n/a`. | Free form language name. |
| last4Ssn | string | No | Must be exactly 4 numeric digits. Cannot be cleared. | Last 4 digits of Social Security Number. |

### Responses

#### 200 OK

Patient record updated successfully.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Person instance ID. |
| firstName | String | No | Legal first name. |
| lastName | String | No | Legal last name / surname. |
| middleName | String | Yes | Middle name or initial. |
| dob | String | No | Date of birth (YYYY-MM-DD). |
| gender | String | Yes | Administrative sex. |
| genderIdentity | String | Yes | Self-reported gender identity. |
| sexAtBirth | String | Yes | Biological sex at birth. |
| race | String | Yes | OMB race category. |
| ethnicity | String | Yes | OMB ethnicity category. |
| preferredLanguage | String | Yes | Preferred language. |
| ssnPreview | String | Yes | Masked SSN preview. Only last 4 digits shown. |
| updatedBy | String | Yes | User who last updated the patient record. |
| updated | LocalDateTime | Yes | Timestamp of the last update. |

#### 400 Bad Request

Invalid request. Possible causes: A required field (firstName, lastName, dob) is missing, blank, or set to n/a; Invalid value for gender, race, or ethnicity; Invalid date format; Date validation failures; last4Ssn is not exactly 4 digits

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'
```

## PATCH /v3/patient/{id}

Partially update a patient record

### Overview

Updates only the fields provided in the request body. Fields not included in the request are left unchanged. Only non-null fields in the request body are applied to the patient record. Existing values for omitted fields are preserved. Value-list fields are validated only when provided. Sending null (or omitting a field) leaves it unchanged, so an optional field is cleared by sending the default value for its type: Text (middleName, genderIdentity, preferredLanguage) — send n/a; Coded (gender, race, ethnicity, sexAtBirth) — send n/a (or Unknown); the field resets to Unknown. firstName, lastName and dob are required and cannot be cleared; last4Ssn accepts only 4 digits and cannot be cleared. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | Long | Yes | The ID of the patient record to partially update. |

### Request Body

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

```json
{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| firstName | string | Yes | Cannot be cleared. | Legal first name. |
| lastName | string | Yes | Cannot be cleared. | Legal last name / surname. |
| middleName | string | No | Optional; clear with `n/a`. | Middle name or initial. |
| dob | string | Yes | Cannot be cleared. | Date of birth in YYYY-MM-DD format. |
| gender | string | No | Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown. | Administrative sex. |
| genderIdentity | string | No | Optional; clear with `n/a`. | Self-reported gender identity (freeform or coded). |
| sexAtBirth | string | No | Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown. | Biological sex at birth. |
| race | string | No | Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown. | OMB race category. |
| ethnicity | string | No | Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown. | OMB ethnicity category. |
| preferredLanguage | string | No | Optional; clear with `n/a`. | Free form language name. |
| last4Ssn | string | No | Must be exactly 4 numeric digits. Cannot be cleared. | Last 4 digits of Social Security Number. |

### Responses

#### 200 OK

Patient record partially updated successfully.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Person instance ID. |
| firstName | String | No | Legal first name. |
| lastName | String | No | Legal last name / surname. |
| middleName | String | Yes | Middle name or initial. |
| dob | String | No | Date of birth (YYYY-MM-DD). |
| gender | String | Yes | Administrative sex. |
| genderIdentity | String | Yes | Self-reported gender identity. |
| sexAtBirth | String | Yes | Biological sex at birth. |
| race | String | Yes | OMB race category. |
| ethnicity | String | Yes | OMB ethnicity category. |
| preferredLanguage | String | Yes | Preferred language. |
| ssnPreview | String | Yes | Masked SSN preview. Only last 4 digits shown. |
| updatedBy | String | Yes | User who last updated the patient record. |
| updated | LocalDateTime | Yes | Timestamp of the last update. |

#### 400 Bad Request

Invalid request. Possible causes: Invalid value for gender, race, or ethnicity; Invalid date format for dob; Date of birth is in the future; last4Ssn is not exactly 4 digits

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'
```

## DELETE /v3/patient/{id}

Delete a patient record

### Overview

Soft-deletes a patient record. The record is marked as deleted but not permanently removed. The patient record is soft-deleted and will no longer appear in queries. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | Long | Yes | The ID of the patient record to delete. |

### Responses

#### 200 OK

Patient record deleted successfully.

**DTO**: `OneHealthResponseDTO`

```json
{
  "id": 1001,
  "name": "example-value",
  "message": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes |  |
| name | String | Yes |  |
| message | String | Yes |  |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

### Example

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

---

## Child Routes

| Path | Methods | Summary | agents.md |
| --- | --- | --- | --- |
| /v3/patient/find | GET |  | https://agents.1health.io/public/demo/api/v3/patient/find/agents.md |
| /v3/patient/{patientId} | — | address, alias, attach, contact, deceased, identifier | https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md |

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