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

**URL**: https://demo.1health.io/api/v3/patient/{patientId}/address

APIs for managing patient physical addresses. Supports creating, listing, updating, and deactivating address records with automatic address validation.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/address | GET | List patient addresses |
| /v3/patient/{patientId}/address | POST | Add a new address to a patient |
| /v3/patient/{patientId}/address/{addressId} | GET | Get a specific patient address |
| /v3/patient/{patientId}/address/{addressId} | PUT | Fully update a patient address |
| /v3/patient/{patientId}/address/{addressId} | PATCH | Partially update a patient address |
| /v3/patient/{patientId}/address/{addressId} | DELETE | Deactivate a patient address |

---

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

List patient addresses

### Overview

Returns all active addresses for a patient. Supports optional filtering by primary status and use type. Returns an array of address records (possibly empty). Only active (non-deleted) addresses are returned. Use ?primary=true to get only the primary address. Use ?use=home to filter by address use type.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| primary | Boolean | No |  | Filter by primary status. When true, returns only the primary address. |
| use | String | No |  | Filter by address use type. |

### Responses

#### 200 OK

List of patient addresses.

**DTO**: `PatientAddressListResponseDTO`

```json
{
  "addresses": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| addresses | List<PatientAddressResponseDTO> | No | List of patient address records. |

#### 400 Bad Request

Invalid use filter value.

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

### Example

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

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

Add a new address to a patient

### Overview

Appends a new physical address to the patient record. Old addresses are preserved for audit trail. The address is validated against the Google Address Validation API. Creates a new address record — existing addresses are not modified. If primary is set to true, any existing primary address is automatically unset. If this is the patient's first address and primary is not specified, it is automatically set as primary. Address validation is performed automatically. The validationStatus field indicates the result: verified, unverified, or unknown. If validation returns unverified, candidate suggestions may be included in validationCandidates. Addresses are never rejected on validation grounds — the record is always created. effectiveFrom defaults to the current date if not provided. country defaults to United States if not provided. Requires authentication. Required fields: line1, city, state, postalCode. use defaults to work if not provided.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient to add an address to. |

### Request Body

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

```json
{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| use | string | Yes | allowableValues: home, work, billing, mailing, temporary | Address use type. |
| line1 | string | Yes |  | Street address line 1. Cannot be cleared. |
| line2 | string | No |  | Apt, suite, unit, floor. Optional; clear with `n/a`. |
| city | string | Yes |  | City or municipality. Cannot be cleared. |
| state | string | Yes |  | State / province / region code. Cannot be cleared. |
| postalCode | string | Yes |  | ZIP or postal code. Cannot be cleared. |
| country | string | No |  | Country name. Valid country names available from /v2/public/countries. |
| primary | boolean | No |  | Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary). |
| effectiveFrom | string | No | format: date | When this address became valid in YYYY-MM-DD format. Defaults to current date. |
| effectiveTo | string | No | format: date | When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective). |

### Responses

#### 201 Created

Address created successfully.

**DTO**: `PatientAddressResponseDTO`

```json
{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Address record ID. |
| use | String | No | Address use type. |
| line1 | String | No | Street address line 1. |
| line2 | String | Yes | Apt, suite, unit, floor. |
| city | String | No | City or municipality. |
| state | String | No | State / province / region code. |
| postalCode | String | No | ZIP or postal code. |
| country | String | Yes | Country name. |
| primary | Boolean | Yes | Whether this is the primary address. |
| effectiveFrom | LocalDate | Yes | When this address became valid. |
| effectiveTo | LocalDate | Yes | When this address stopped being valid. Null means current. |
| validationStatus | String | Yes | Address validation status. |
| validationCandidates | List<Map<String, String>> | Yes | Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'. |

#### 400 Bad Request

Invalid request. Possible causes: A required field (line1, city, state, postalCode) is missing, blank, or set to n/a; Invalid use value; Invalid date format for effectiveFrom or effectiveTo; effectiveTo is before effectiveFrom

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient/1001/address" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

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

Get a specific patient address

### Overview

Returns a single address record for a patient. Requires authentication. Returns 404 if the address ID is not found for this patient.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |
| addressId | Long | Yes | The ID of the address record. |

### Responses

#### 200 OK

Address record found.

**DTO**: `PatientAddressResponseDTO`

```json
{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Address record ID. |
| use | String | No | Address use type. |
| line1 | String | No | Street address line 1. |
| line2 | String | Yes | Apt, suite, unit, floor. |
| city | String | No | City or municipality. |
| state | String | No | State / province / region code. |
| postalCode | String | No | ZIP or postal code. |
| country | String | Yes | Country name. |
| primary | Boolean | Yes | Whether this is the primary address. |
| effectiveFrom | LocalDate | Yes | When this address became valid. |
| effectiveTo | LocalDate | Yes | When this address stopped being valid. Null means current. |
| validationStatus | String | Yes | Address validation status. |
| validationCandidates | List<Map<String, String>> | Yes | Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Address not found — re-fetch the list to find the current record.

### Example

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

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

Fully update a patient address

### Overview

Replaces all fields of an existing address record. All required fields must be provided. Re-validation is triggered if address data has changed or the current status is unknown. If primary is changed to true, the previous primary address is automatically unset. Address validation is re-triggered when address fields change or the current validationStatus is unknown. Requires authentication. Returns 404 if the address does not exist for this patient.

### Authorization

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

### Path Parameters

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

### Request Body

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

```json
{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| use | string | Yes | allowableValues: home, work, billing, mailing, temporary | Address use type. |
| line1 | string | Yes |  | Street address line 1. Cannot be cleared. |
| line2 | string | No |  | Apt, suite, unit, floor. Optional; clear with `n/a`. |
| city | string | Yes |  | City or municipality. Cannot be cleared. |
| state | string | Yes |  | State / province / region code. Cannot be cleared. |
| postalCode | string | Yes |  | ZIP or postal code. Cannot be cleared. |
| country | string | No |  | Country name. Valid country names available from /v2/public/countries. |
| primary | boolean | No |  | Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary). |
| effectiveFrom | string | No | format: date | When this address became valid in YYYY-MM-DD format. Defaults to current date. |
| effectiveTo | string | No | format: date | When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective). |

### Responses

#### 200 OK

Address updated successfully.

**DTO**: `PatientAddressResponseDTO`

```json
{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Address record ID. |
| use | String | No | Address use type. |
| line1 | String | No | Street address line 1. |
| line2 | String | Yes | Apt, suite, unit, floor. |
| city | String | No | City or municipality. |
| state | String | No | State / province / region code. |
| postalCode | String | No | ZIP or postal code. |
| country | String | Yes | Country name. |
| primary | Boolean | Yes | Whether this is the primary address. |
| effectiveFrom | LocalDate | Yes | When this address became valid. |
| effectiveTo | LocalDate | Yes | When this address stopped being valid. Null means current. |
| validationStatus | String | Yes | Address validation status. |
| validationCandidates | List<Map<String, String>> | Yes | Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'. |

#### 400 Bad Request

Invalid request. Possible causes: A required field (line1, city, state, postalCode) is missing, blank, or set to n/a; Invalid use value; Invalid date format for effectiveFrom or effectiveTo; effectiveTo is before effectiveFrom; Cannot unset primary without setting another address as primary first

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or address not found.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001/address/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

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

Partially update a patient address

### Overview

Updates only the fields provided in the request body. Fields not included are left unchanged. Re-validation is triggered if address fields change or the current status is unknown. Only non-null fields are applied. Existing values for omitted fields are preserved. Sending null (or omitting a field) leaves it unchanged, so an optional field is cleared by sending the default value for its type: Text (line2) — send n/a; Date (effectiveTo) — send 1970-01-01 to clear the end date so the address is treated as currently effective; Boolean (primary) — send false to unset it (allowed only when another address is already primary); effectiveFrom cannot be emptied; sending it blank resets it to the current date; line1, city, state and postalCode are required and cannot be cleared.

### Authorization

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

### Path Parameters

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

### Request Body

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

```json
{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| use | string | Yes | allowableValues: home, work, billing, mailing, temporary | Address use type. |
| line1 | string | Yes |  | Street address line 1. Cannot be cleared. |
| line2 | string | No |  | Apt, suite, unit, floor. Optional; clear with `n/a`. |
| city | string | Yes |  | City or municipality. Cannot be cleared. |
| state | string | Yes |  | State / province / region code. Cannot be cleared. |
| postalCode | string | Yes |  | ZIP or postal code. Cannot be cleared. |
| country | string | No |  | Country name. Valid country names available from /v2/public/countries. |
| primary | boolean | No |  | Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary). |
| effectiveFrom | string | No | format: date | When this address became valid in YYYY-MM-DD format. Defaults to current date. |
| effectiveTo | string | No | format: date | When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective). |

### Responses

#### 200 OK

Address partially updated successfully.

**DTO**: `PatientAddressResponseDTO`

```json
{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Address record ID. |
| use | String | No | Address use type. |
| line1 | String | No | Street address line 1. |
| line2 | String | Yes | Apt, suite, unit, floor. |
| city | String | No | City or municipality. |
| state | String | No | State / province / region code. |
| postalCode | String | No | ZIP or postal code. |
| country | String | Yes | Country name. |
| primary | Boolean | Yes | Whether this is the primary address. |
| effectiveFrom | LocalDate | Yes | When this address became valid. |
| effectiveTo | LocalDate | Yes | When this address stopped being valid. Null means current. |
| validationStatus | String | Yes | Address validation status. |
| validationCandidates | List<Map<String, String>> | Yes | Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'. |

#### 400 Bad Request

Invalid request. Possible causes: Invalid use value; Invalid date format for effectiveFrom or effectiveTo; effectiveTo is before effectiveFrom; Attempting to clear a required field (line1, city, state, postalCode); Cannot unset primary without setting another address as primary first

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or address not found.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/address/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

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

Deactivate a patient address

### Overview

Soft-deletes an address record. The address is deactivated but preserved for audit trail. Requires authentication. Cannot delete a primary address — first set another address as primary. Returns 404 if the address does not exist.

### Authorization

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

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |
| addressId | Long | Yes | The ID of the address record to deactivate. |

### Responses

#### 200 OK

Address deactivated successfully.

**DTO**: `OneHealthResponseDTO`

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

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

#### 400 Bad Request

Cannot delete primary address — set another as primary first.

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or address not found.

### Example

```bash
curl -X DELETE "https://demo.1health.io/api/v3/patient/1001/address/1001" \
  -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