# /v3/patient/{patientId}/address/{addressId}

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


Manages patient physical address records in the Patient Vault. Supports creating new addresses, listing all active addresses with optional filtering, retrieving a single address, fully replacing an address (PUT), partially updating an address (PATCH), and soft-deleting an address. Address data is automatically validated against the Google Address Validation API on create and on update when address fields change.

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

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/address/{addressId}` | GET |  |
| `/v3/patient/{patientId}/address/{addressId}` | PUT |  |
| `/v3/patient/{patientId}/address/{addressId}` | PATCH |  |
| `/v3/patient/{patientId}/address/{addressId}` | DELETE |  |

---

## GET /v3/patient/{patientId}/address/{addressId}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{patientId}/address/{addressId}` |
| **Method** | `GET` |
| **Authentication** | Required (session-based via `TenantContext`) |
| **Content-Type** | `application/json` |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `patientId` | Long | Yes | ID of the patient whose addresses are being managed. Applies to all six endpoints. |
| `addressId` | Long | Yes | ID of the specific address record. Applies to GET `/{addressId}`, PUT, PATCH, and DELETE. |



## Response


### Success Response

---

**GET /v3/patient/{patientId}/address/{addressId}** — HTTP 200 OK — **DTO**: `PatientAddressResponseDTO`

Same structure as the POST 201 response body above.

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | A required field (`line1`, `city`, `state`, `postalCode`) is missing, blank, or `n/a` | `BadRequestException` with field name |
| 400 | Invalid `use` value supplied | `BadRequestException` with the invalid value |
| 400 | Invalid date format for `effectiveFrom` or `effectiveTo` | `BadRequestException` with message |
| 400 | `effectiveTo` is before `effectiveFrom` | `BadRequestException` |
| 400 | Attempting to unset `primary` when no other primary address exists | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 400 | Attempting to delete a primary address | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 401 | No valid session | Unauthorized |
| 404 | Patient not found for the given `patientId` and tenant | `NotFoundException` (`Messages.PATIENT_VAULT_PATIENT_NOT_FOUND`) |
| 404 | Address not found for the given `addressId` and `patientId` | `NotFoundException` (`Messages.PATIENT_VAULT_ADDRESS_NOT_FOUND`) |

---

## PUT /v3/patient/{patientId}/address/{addressId}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{patientId}/address/{addressId}` |
| **Method** | `PUT` |
| **Authentication** | Required (session-based via `TenantContext`) |
| **Content-Type** | `application/json` |

## Request Body


### PUT /v3/patient/{patientId}/address/{addressId}

**DTO**: `PatientAddressRequestDTO` — same structure as POST. All required fields (`line1`, `city`, `state`, `postalCode`) must be present. Address re-validation is triggered when address fields have changed or the existing `validationStatus` is `unknown`.



## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `patientId` | Long | Yes | ID of the patient whose addresses are being managed. Applies to all six endpoints. |
| `addressId` | Long | Yes | ID of the specific address record. Applies to GET `/{addressId}`, PUT, PATCH, and DELETE. |



## Response


### Success Response

---

**PUT /v3/patient/{patientId}/address/{addressId}** — HTTP 200 OK — **DTO**: `PatientAddressResponseDTO`

Same structure as the POST 201 response body above.

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | A required field (`line1`, `city`, `state`, `postalCode`) is missing, blank, or `n/a` | `BadRequestException` with field name |
| 400 | Invalid `use` value supplied | `BadRequestException` with the invalid value |
| 400 | Invalid date format for `effectiveFrom` or `effectiveTo` | `BadRequestException` with message |
| 400 | `effectiveTo` is before `effectiveFrom` | `BadRequestException` |
| 400 | Attempting to unset `primary` when no other primary address exists | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 400 | Attempting to delete a primary address | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 401 | No valid session | Unauthorized |
| 404 | Patient not found for the given `patientId` and tenant | `NotFoundException` (`Messages.PATIENT_VAULT_PATIENT_NOT_FOUND`) |
| 404 | Address not found for the given `addressId` and `patientId` | `NotFoundException` (`Messages.PATIENT_VAULT_ADDRESS_NOT_FOUND`) |

---

## PATCH /v3/patient/{patientId}/address/{addressId}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{patientId}/address/{addressId}` |
| **Method** | `PATCH` |
| **Authentication** | Required (session-based via `TenantContext`) |
| **Content-Type** | `application/json` |

## Request Body


### PATCH /v3/patient/{patientId}/address/{addressId}

**DTO**: `PatientAddressRequestDTO` — same structure as POST. Only non-null fields are applied; omitted fields retain their existing values. Required fields (`line1`, `city`, `state`, `postalCode`) cannot be cleared by sending blank or `n/a`. To clear `line2`, send `n/a`. To clear `effectiveTo`, send `1970-01-01`. To unset `primary`, send `false` (only allowed when another address is already primary).



## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `patientId` | Long | Yes | ID of the patient whose addresses are being managed. Applies to all six endpoints. |
| `addressId` | Long | Yes | ID of the specific address record. Applies to GET `/{addressId}`, PUT, PATCH, and DELETE. |



## Response


### Success Response

---

**PATCH /v3/patient/{patientId}/address/{addressId}** — HTTP 200 OK — **DTO**: `PatientAddressResponseDTO`

Same structure as the POST 201 response body above.

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | A required field (`line1`, `city`, `state`, `postalCode`) is missing, blank, or `n/a` | `BadRequestException` with field name |
| 400 | Invalid `use` value supplied | `BadRequestException` with the invalid value |
| 400 | Invalid date format for `effectiveFrom` or `effectiveTo` | `BadRequestException` with message |
| 400 | `effectiveTo` is before `effectiveFrom` | `BadRequestException` |
| 400 | Attempting to unset `primary` when no other primary address exists | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 400 | Attempting to delete a primary address | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 401 | No valid session | Unauthorized |
| 404 | Patient not found for the given `patientId` and tenant | `NotFoundException` (`Messages.PATIENT_VAULT_PATIENT_NOT_FOUND`) |
| 404 | Address not found for the given `addressId` and `patientId` | `NotFoundException` (`Messages.PATIENT_VAULT_ADDRESS_NOT_FOUND`) |

---

## DELETE /v3/patient/{patientId}/address/{addressId}

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/{patientId}/address/{addressId}` |
| **Method** | `DELETE` |
| **Authentication** | Required (session-based via `TenantContext`) |
| **Content-Type** | `application/json` |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `patientId` | Long | Yes | ID of the patient whose addresses are being managed. Applies to all six endpoints. |
| `addressId` | Long | Yes | ID of the specific address record. Applies to GET `/{addressId}`, PUT, PATCH, and DELETE. |



## Response


### Success Response

---

**DELETE /v3/patient/{patientId}/address/{addressId}** — HTTP 200 OK — **DTO**: `OneHealthResponseDTO`

```json
{
  "message": "Address successfully deleted.",
  "id": 67890,
  "name": "<address name>"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `message` | String | Confirmation message formatted as `"Address successfully deleted."` |
| `id` | Long | ID of the deactivated address record. |
| `name` | String | Internal name of the address record (generated by `OneHealthUtil.buildAddressName()`). |

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | A required field (`line1`, `city`, `state`, `postalCode`) is missing, blank, or `n/a` | `BadRequestException` with field name |
| 400 | Invalid `use` value supplied | `BadRequestException` with the invalid value |
| 400 | Invalid date format for `effectiveFrom` or `effectiveTo` | `BadRequestException` with message |
| 400 | `effectiveTo` is before `effectiveFrom` | `BadRequestException` |
| 400 | Attempting to unset `primary` when no other primary address exists | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 400 | Attempting to delete a primary address | `BadRequestException` (`Messages.SET_PRIMARY_LOCATION`) |
| 401 | No valid session | Unauthorized |
| 404 | Patient not found for the given `patientId` and tenant | `NotFoundException` (`Messages.PATIENT_VAULT_PATIENT_NOT_FOUND`) |
| 404 | Address not found for the given `addressId` and `patientId` | `NotFoundException` (`Messages.PATIENT_VAULT_ADDRESS_NOT_FOUND`) |

---