# /v3/patient/{id}

`GET`  `PUT`  `PATCH`  `DELETE`


Manages patient demographic records in the Patient Vault: list all patients, retrieve a single patient by ID, find patients by demographic criteria, create a new patient record, fully replace a patient record, partially update a patient record, and soft-delete a patient record.

**Authentication**: Bearer JWT required for all endpoints.

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/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 | Soft-delete a patient record |

---

## GET /v3/patient/{id}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{id}` |
| **Method** | `GET` |
| **Authentication** | Required — valid session |
| **Content-Type** | `application/json` |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | Long | Yes | ID of the patient record (GET by ID, PUT, PATCH, DELETE). |



## Response


### Success Response (200 OK)

**GET /v3/patient/{id}** — **DTO**: `PatientResponseDTO`

```json
{
  "id": 12345,
  "firstName": "Maria",
  "lastName": "Santos",
  "dob": "1988-04-12",
  "middleName": "Elena",
  "gender": "female",
  "race": "asian",
  "ethnicity": "not_hispanic",
  "sexAtBirth": "female",
  "genderIdentity": "woman",
  "preferredLanguage": "English",
  "last4Ssn": "***-**-1234",
  "deceased": false
}
```

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

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | `firstName`, `lastName`, or `dob` is missing, blank, or `n/a` (POST/PUT) | Validation error with message |
| 400 | Invalid value for `gender`, `race`, or `ethnicity` | Validation error with message |
| 400 | Invalid date format for `dob` | Validation error with message |
| 400 | Date of birth is in the future | Validation error with message |
| 400 | `last4Ssn` is not exactly 4 digits | Validation error with message |
| 400 | No demographic criteria provided to `/find` (GET) | Validation error with message |
| 400 | Invalid `sexAtBirth` value supplied to `/find` | Validation error with message |
| 401 | No valid session | Not authenticated |
| 404 | Patient with the specified ID does not exist in the current tenant (GET by ID, PUT, PATCH, DELETE) | Not found error with message |



## Example Request


### GET /v3/patient/{id} — Get a patient record by ID

```bash
curl -X GET "https://demo.1health.io/v3/patient/12345"
```



## Related Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/deceased` | GET | Retrieve the deceased status of a patient. |
| `/v3/patient/{patientId}/deceased` | POST | Mark a patient as deceased. |
| `/v3/patient/{patientId}/deceased` | DELETE | Remove the deceased status from a patient. |

---

## PUT /v3/patient/{id}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{id}` |
| **Method** | `PUT` |
| **Authentication** | Required — valid session |
| **Content-Type** | `application/json` |

## Request Body


### PUT /v3/patient/{id}

**DTO**: `PatientRequestDTO` — same structure as POST. All required fields must be present. Optional fields omitted from the request body are cleared (set to null).



## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | Long | Yes | ID of the patient record (GET by ID, PUT, PATCH, DELETE). |



## Response


### Success Response (200 OK)

**PUT /v3/patient/{id}** — **DTO**: `PatientResponseDTO`

Same structure as POST response. Returns the fully updated patient record.

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | `firstName`, `lastName`, or `dob` is missing, blank, or `n/a` (POST/PUT) | Validation error with message |
| 400 | Invalid value for `gender`, `race`, or `ethnicity` | Validation error with message |
| 400 | Invalid date format for `dob` | Validation error with message |
| 400 | Date of birth is in the future | Validation error with message |
| 400 | `last4Ssn` is not exactly 4 digits | Validation error with message |
| 400 | No demographic criteria provided to `/find` (GET) | Validation error with message |
| 400 | Invalid `sexAtBirth` value supplied to `/find` | Validation error with message |
| 401 | No valid session | Not authenticated |
| 404 | Patient with the specified ID does not exist in the current tenant (GET by ID, PUT, PATCH, DELETE) | Not found error with message |



## Example Request


### PUT /v3/patient/{id} — Fully update a patient record

```bash
curl -X PUT "https://demo.1health.io/v3/patient/12345" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Santos-Rivera",
    "dob": "1988-04-12",
    "gender": "female",
    "race": "asian",
    "ethnicity": "not_hispanic"
  }'
```



## Related Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/deceased` | GET | Retrieve the deceased status of a patient. |
| `/v3/patient/{patientId}/deceased` | POST | Mark a patient as deceased. |
| `/v3/patient/{patientId}/deceased` | DELETE | Remove the deceased status from a patient. |

---

## PATCH /v3/patient/{id}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{id}` |
| **Method** | `PATCH` |
| **Authentication** | Required — valid session |
| **Content-Type** | `application/json` |

## Request Body


### PATCH /v3/patient/{id}

**DTO**: `PatientRequestDTO` — same structure as POST. Only non-null fields in the request body are applied. Omitted fields remain unchanged. To clear an optional text field, send `n/a`; to reset a coded field, send `n/a` or `Unknown`.



## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | Long | Yes | ID of the patient record (GET by ID, PUT, PATCH, DELETE). |



## Response


### Success Response (200 OK)

**PATCH /v3/patient/{id}** — **DTO**: `PatientResponseDTO`

Same structure as POST response. Returns the patient record after partial update.

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | `firstName`, `lastName`, or `dob` is missing, blank, or `n/a` (POST/PUT) | Validation error with message |
| 400 | Invalid value for `gender`, `race`, or `ethnicity` | Validation error with message |
| 400 | Invalid date format for `dob` | Validation error with message |
| 400 | Date of birth is in the future | Validation error with message |
| 400 | `last4Ssn` is not exactly 4 digits | Validation error with message |
| 400 | No demographic criteria provided to `/find` (GET) | Validation error with message |
| 400 | Invalid `sexAtBirth` value supplied to `/find` | Validation error with message |
| 401 | No valid session | Not authenticated |
| 404 | Patient with the specified ID does not exist in the current tenant (GET by ID, PUT, PATCH, DELETE) | Not found error with message |



## Example Request


### PATCH /v3/patient/{id} — Partially update a patient record

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



## Related Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/deceased` | GET | Retrieve the deceased status of a patient. |
| `/v3/patient/{patientId}/deceased` | POST | Mark a patient as deceased. |
| `/v3/patient/{patientId}/deceased` | DELETE | Remove the deceased status from a patient. |

---

## DELETE /v3/patient/{id}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{id}` |
| **Method** | `DELETE` |
| **Authentication** | Required — valid session |
| **Content-Type** | `application/json` |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | Long | Yes | ID of the patient record (GET by ID, PUT, PATCH, DELETE). |



## Response


### Success Response (200 OK)

**DELETE /v3/patient/{id}** — **DTO**: `OneHealthResponseDTO`

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

| Field | Type | Description |
|-------|------|-------------|
| `message` | String | Confirmation message. |

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | `firstName`, `lastName`, or `dob` is missing, blank, or `n/a` (POST/PUT) | Validation error with message |
| 400 | Invalid value for `gender`, `race`, or `ethnicity` | Validation error with message |
| 400 | Invalid date format for `dob` | Validation error with message |
| 400 | Date of birth is in the future | Validation error with message |
| 400 | `last4Ssn` is not exactly 4 digits | Validation error with message |
| 400 | No demographic criteria provided to `/find` (GET) | Validation error with message |
| 400 | Invalid `sexAtBirth` value supplied to `/find` | Validation error with message |
| 401 | No valid session | Not authenticated |
| 404 | Patient with the specified ID does not exist in the current tenant (GET by ID, PUT, PATCH, DELETE) | Not found error with message |



## Example Request


### DELETE /v3/patient/{id} — Soft-delete a patient record

```bash
curl -X DELETE "https://demo.1health.io/v3/patient/12345"
```



## Related Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/deceased` | GET | Retrieve the deceased status of a patient. |
| `/v3/patient/{patientId}/deceased` | POST | Mark a patient as deceased. |
| `/v3/patient/{patientId}/deceased` | DELETE | Remove the deceased status from a patient. |

---