---
schema: agents-md/1.0
site_root: https://dev.1health.io/api/
route: /v3/patient
site_path: /v3/patient/agents.md
kind: endpoints
methods: [GET, POST, PATCH, DELETE]
api_version: v3
parent: /v3/agents.md
source_version: staging-20260814 (app-observed routes; OpenAPI via 1H docs MCP; no pinned spec SHA)
generated_at: 2026-08-14T03:30:00Z
---

# /v3/patient

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.

## Endpoints

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

**Base URLs**: production `https://1health.app.1health.io/api` · demo `https://demo.1health.io/api`

---

## 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.

**Behavior & Use Cases**
- 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`

**Important Notes**
- Requires authentication
- `page` is zero-based and defaults to `0`
- `size` defaults to `50`

### Authorization

Required — valid session (API key `apiKeyAuth` or Bearer token `bearerAuth`). See the [authentication quickstart](https://dev.1health.io/api/authentication/agents.md).

### Query Parameters

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

### Responses

#### 200

Paginated list of patient records (possibly empty).

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

```json
{
  "content": [
    {
      "id": 12345,
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1990-05-15",
      "middleName": "Michael",
      "gender": "Unknown",
      "race": "Unknown",
      "ethnicity": "Unknown",
      "sexAtBirth": "male",
      "genderIdentity": "n/a",
      "preferredLanguage": "English",
      "last4Ssn": "***-**-1234",
      "deceased": false
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1
}
```

| Field | Type | Nullable | Description |
|---|---|---|---|
| content | List<PatientResponseDTO> | No | Page of patient records. |
| page | Integer | No | Current zero-based page index. |
| size | Integer | No | Page size. |
| totalElements | Long | No | Total number of matching records. |

#### 401

Not authenticated — valid session required.

**DTO**: `PagePatientResponseDTO`

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient?page=0&size=50" \
  -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.

**Duplicate handling**
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.

**Behavior & Use Cases**
- 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

**Important Notes**
- 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

Required — valid session (API key `apiKeyAuth` or Bearer token `bearerAuth`). See the [authentication quickstart](https://dev.1health.io/api/authentication/agents.md).

### Request Body

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

```json
{
  "firstName": "John",
  "lastName": "Doe",
  "dob": "1990-05-15",
  "middleName": "Michael",
  "sexAtBirth": "male",
  "preferredLanguage": "English",
  "last4Ssn": "1234"
}
```

| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| firstName | String | Yes |  | Patient's given name. Cannot be blank or `n/a`. |
| lastName | String | Yes |  | Patient's family name. Cannot be blank or `n/a`. |
| dob | String | Yes |  | Date of birth in `YYYY-MM-DD` format. Cannot be in the future. |
| middleName | String | No |  | Patient's middle name. |
| gender | String | No |  | Gender value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| race | String | No |  | Race value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| ethnicity | String | No |  | Ethnicity value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| sexAtBirth | String | No |  | Biological sex at birth. Allowed values: `male`, `female`, `intersex`, `unknown`. |
| genderIdentity | String | No |  | Free-text gender identity. |
| preferredLanguage | String | No |  | Patient's preferred language. |
| last4Ssn | String | No |  | Last 4 digits of SSN. Stored as masked value (e.g. `***-**-1234`). Must be exactly 4 digits if provided. |

### Responses

#### 200

Patient record created successfully.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 12345,
  "firstName": "John",
  "lastName": "Doe",
  "dob": "1990-05-15",
  "middleName": "Michael",
  "gender": "Unknown",
  "race": "Unknown",
  "ethnicity": "Unknown",
  "sexAtBirth": "male",
  "genderIdentity": "n/a",
  "preferredLanguage": "English",
  "last4Ssn": "***-**-1234",
  "deceased": false
}
```

| Field | Type | Nullable | Description |
|---|---|---|---|
| id | Long | No | Patient record ID. |
| firstName | String | No | Patient's given name. |
| lastName | String | No | Patient's family name. |
| dob | String | No | Date of birth (`YYYY-MM-DD`). |
| middleName | String | No | Patient's middle name. |
| gender | String | No | Gender value. |
| race | String | No | Race value. |
| ethnicity | String | No | Ethnicity value. |
| sexAtBirth | String | No | Biological sex at birth. |
| genderIdentity | String | No | Free-text gender identity. |
| preferredLanguage | String | No | Patient's preferred language. |
| last4Ssn | String | No | Masked SSN preview (e.g. `***-**-1234`). Full SSN is never returned. |
| deceased | Boolean | No | Whether the patient is marked as deceased. Managed via `/v3/patient/{patientId}/deceased`. |

#### 400

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.

**DTO**: `PatientResponseDTO`

#### 401

Not authenticated — valid session required.

**DTO**: `PatientResponseDTO`

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"John","lastName":"Doe","dob":"1990-05-15","sexAtBirth":"male","last4Ssn":"1234"}'
```

---

## GET /v3/patient/{patientId}

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.

**Behavior & Use Cases**
- 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`)

**Important Notes**
- Requires authentication
- Idempotent — repeated calls return the same result
- Returns 404 if the patient does not exist in the current tenant

### Authorization

Required — valid session (API key `apiKeyAuth` or Bearer token `bearerAuth`). See the [authentication quickstart](https://dev.1health.io/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| patientId | Long | Yes | The ID of the patient record to retrieve. (Documented in the OpenAPI spec as path parameter `id`.) |

### Responses

#### 200

Patient record found.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 12345,
  "firstName": "John",
  "lastName": "Doe",
  "dob": "1990-05-15",
  "middleName": "Michael",
  "gender": "Unknown",
  "race": "Unknown",
  "ethnicity": "Unknown",
  "sexAtBirth": "male",
  "genderIdentity": "n/a",
  "preferredLanguage": "English",
  "last4Ssn": "***-**-1234",
  "deceased": false
}
```

| Field | Type | Nullable | Description |
|---|---|---|---|
| id | Long | No | Patient record ID. |
| firstName | String | No | Patient's given name. |
| lastName | String | No | Patient's family name. |
| dob | String | No | Date of birth (`YYYY-MM-DD`). |
| middleName | String | No | Patient's middle name. |
| gender | String | No | Gender value. |
| race | String | No | Race value. |
| ethnicity | String | No | Ethnicity value. |
| sexAtBirth | String | No | Biological sex at birth. |
| genderIdentity | String | No | Free-text gender identity. |
| preferredLanguage | String | No | Patient's preferred language. |
| last4Ssn | String | No | Masked SSN preview (e.g. `***-**-1234`). Full SSN is never returned. |
| deceased | Boolean | No | Whether the patient is marked as deceased. Managed via `/v3/patient/{patientId}/deceased`. |

#### 401

Not authenticated — valid session required.

**DTO**: `PatientResponseDTO`

#### 404

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

**DTO**: `PatientResponseDTO`

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient/12345" \
  -H "Authorization: Bearer <token>"
```

---

## PATCH /v3/patient/{patientId}

Partially update a patient record

### Overview

Updates only the fields provided in the request body. Fields not included in the request are left unchanged.

**Behavior & Use Cases**
- 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

**Clearing a value**
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

**Important Notes**
- Requires authentication
- Returns 404 if the patient does not exist in the current tenant

### Authorization

Required — valid session (API key `apiKeyAuth` or Bearer token `bearerAuth`). See the [authentication quickstart](https://dev.1health.io/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| patientId | Long | Yes | The ID of the patient record to partially update. (Documented in the OpenAPI spec as path parameter `id`.) |

### Request Body

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

```json
{
  "preferredLanguage": "Spanish"
}
```

| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| firstName | String | Yes |  | Patient's given name. Cannot be blank or `n/a`. |
| lastName | String | Yes |  | Patient's family name. Cannot be blank or `n/a`. |
| dob | String | Yes |  | Date of birth in `YYYY-MM-DD` format. Cannot be in the future. |
| middleName | String | No |  | Patient's middle name. |
| gender | String | No |  | Gender value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| race | String | No |  | Race value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| ethnicity | String | No |  | Ethnicity value. Validated against allowed values. Defaults to `Unknown` if omitted. |
| sexAtBirth | String | No |  | Biological sex at birth. Allowed values: `male`, `female`, `intersex`, `unknown`. |
| genderIdentity | String | No |  | Free-text gender identity. |
| preferredLanguage | String | No |  | Patient's preferred language. |
| last4Ssn | String | No |  | Last 4 digits of SSN. Stored as masked value (e.g. `***-**-1234`). Must be exactly 4 digits if provided. |

### Responses

#### 200

Patient record partially updated successfully.

**DTO**: `PatientResponseDTO`

```json
{
  "id": 12345,
  "firstName": "John",
  "lastName": "Doe",
  "dob": "1990-05-15",
  "middleName": "Michael",
  "gender": "Unknown",
  "race": "Unknown",
  "ethnicity": "Unknown",
  "sexAtBirth": "male",
  "genderIdentity": "n/a",
  "preferredLanguage": "Spanish",
  "last4Ssn": "***-**-1234",
  "deceased": false
}
```

| Field | Type | Nullable | Description |
|---|---|---|---|
| id | Long | No | Patient record ID. |
| firstName | String | No | Patient's given name. |
| lastName | String | No | Patient's family name. |
| dob | String | No | Date of birth (`YYYY-MM-DD`). |
| middleName | String | No | Patient's middle name. |
| gender | String | No | Gender value. |
| race | String | No | Race value. |
| ethnicity | String | No | Ethnicity value. |
| sexAtBirth | String | No | Biological sex at birth. |
| genderIdentity | String | No | Free-text gender identity. |
| preferredLanguage | String | No | Patient's preferred language. |
| last4Ssn | String | No | Masked SSN preview (e.g. `***-**-1234`). Full SSN is never returned. |
| deceased | Boolean | No | Whether the patient is marked as deceased. Managed via `/v3/patient/{patientId}/deceased`. |

#### 400

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.

**DTO**: `PatientResponseDTO`

#### 401

Not authenticated — valid session required.

**DTO**: `PatientResponseDTO`

#### 404

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

**DTO**: `PatientResponseDTO`

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/12345" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"preferredLanguage":"Spanish"}'
```

---

## DELETE /v3/patient/{patientId}

Delete a patient record

### Overview

Soft-deletes a patient record. The record is marked as deleted but not permanently removed.

**Behavior & Use Cases**
- The patient record is soft-deleted and will no longer appear in queries

**Important Notes**
- Requires authentication
- Returns 404 if the patient does not exist in the current tenant

### Authorization

Required — valid session (API key `apiKeyAuth` or Bearer token `bearerAuth`). See the [authentication quickstart](https://dev.1health.io/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| patientId | Long | Yes | The ID of the patient record to delete. (Documented in the OpenAPI spec as path parameter `id`.) |

### Responses

#### 200

Patient record deleted successfully.

**DTO**: `OneHealthResponseDTO`

```json
{
  "message": "Patient record deleted successfully."
}
```

| Field | Type | Nullable | Description |
|---|---|---|---|
| message | String | No | Confirmation message. |

#### 401

Not authenticated — valid session required.

**DTO**: `OneHealthResponseDTO`

#### 404

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

**DTO**: `OneHealthResponseDTO`

### Example

```bash
curl -X DELETE "https://demo.1health.io/api/v3/patient/12345" \
  -H "Authorization: Bearer <token>"
```

---

**Worked examples from production apps**: [examples.md](./examples.md)

## Child Routes

| Path | Methods | Summary | agents.md |
|------|---------|---------|-----------|
| /v3/patient/find | GET | Find patients matching demographic criteria | https://dev.1health.io/api/v3/patient/find/agents.md |
| /v3/patient/{patientId} | — | address, attach, contact, deceased | https://dev.1health.io/api/v3/patient/_patientId_/agents.md |

## Navigation

Parent: https://dev.1health.io/api/v3/agents.md ·
Site guide: https://dev.1health.io/api/agents.md