---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/patient/{patientId}/contact"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/contact/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_/contact/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/contact/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/contact/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}/contact

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

APIs for managing patient contact points (email, phone, fax). Supports creating, listing, updating, and deactivating contact points. The collection is append-only — old contact points are retained for audit and outreach history.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/contact | GET | List patient contact points |
| /v3/patient/{patientId}/contact | POST | Add a new contact point to a patient |
| /v3/patient/{patientId}/contact/{contactId} | GET | Get a specific patient contact point |
| /v3/patient/{patientId}/contact/{contactId} | PUT | Fully update a patient contact point |
| /v3/patient/{patientId}/contact/{contactId} | PATCH | Partially update a patient contact point |
| /v3/patient/{patientId}/contact/{contactId} | DELETE | Deactivate a patient contact point |

---

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

List patient contact points

### Overview

Returns all active contact points for a patient. Supports optional filtering by type and primary status.

### 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 |
| --- | --- | --- | --- | --- |
| type | String | No |  | Filter by contact point type. |
| primary | Boolean | No |  | When true, returns only primary contact points. |

### Responses

#### 200 OK

List of patient contact points.

**DTO**: `PatientContactListResponseDTO`

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

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| contacts | List<PatientContactResponseDTO> | No | List of contact point records. |

#### 400 Bad Request

Invalid type filter value.

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

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

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

Add a new contact point to a patient

### Overview

Appends a new contact point to the patient record. Old contact points are preserved for audit trail — each call creates a new record with its own ID.

### 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 a contact point to. |

### Request Body

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

```json
{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | Cannot be cleared. | The type of contact point. Cannot be cleared. |
| value | string | Yes | Cannot be cleared. | The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100). |
| label | string | No | Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |
| isPrimary | boolean | No | Only one contact point per type can be primary at a time. | Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary. |
| notificationsEnabled | boolean | No | Defaults to `false`. | Whether this contact point may receive notifications. Defaults to `false`. |
| region | string | No | Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |

### Responses

#### 201 Created

Contact point created successfully.

**DTO**: `PatientContactResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Contact point record ID. |
| type | String | Yes | The type of contact point. |
| value | String | Yes | The address or number for this contact point. |
| label | String | Yes | Free-text label for this contact point. |
| isPrimary | Boolean | Yes | Whether this is the preferred contact point for its type. |
| notificationsEnabled | Boolean | Yes | Whether this contact point may receive notifications. |
| region | String | Yes | Region hint for phone normalization. |

#### 400 Bad Request

Invalid request. Possible causes: • A required field (type, value) is missing, blank, or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient/1001/contact" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'
```

## GET /v3/patient/{patientId}/contact/{contactId}

Get a specific patient contact point

### Overview

Returns a single contact point for a 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. |
| contactId | Long | Yes | The ID of the contact point record. |

### Responses

#### 200 OK

Contact point found.

**DTO**: `PatientContactResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Contact point record ID. |
| type | String | Yes | The type of contact point. |
| value | String | Yes | The address or number for this contact point. |
| label | String | Yes | Free-text label for this contact point. |
| isPrimary | Boolean | Yes | Whether this is the preferred contact point for its type. |
| notificationsEnabled | Boolean | Yes | Whether this contact point may receive notifications. |
| region | String | Yes | Region hint for phone normalization. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Contact point not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

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

## PUT /v3/patient/{patientId}/contact/{contactId}

Fully update a patient contact point

### Overview

Replaces all fields of an existing contact point. Required fields must be provided; optional fields absent or sent blank are reset to their default value.

### 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. |
| contactId | Long | Yes | The ID of the contact point to update. |

### Request Body

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

```json
{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | Cannot be cleared. | The type of contact point. Cannot be cleared. |
| value | string | Yes | Cannot be cleared. | The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100). |
| label | string | No | Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |
| isPrimary | boolean | No | Only one contact point per type can be primary at a time. | Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary. |
| notificationsEnabled | boolean | No | Defaults to `false`. | Whether this contact point may receive notifications. Defaults to `false`. |
| region | string | No | Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |

### Responses

#### 200 OK

Contact point updated successfully.

**DTO**: `PatientContactResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Contact point record ID. |
| type | String | Yes | The type of contact point. |
| value | String | Yes | The address or number for this contact point. |
| label | String | Yes | Free-text label for this contact point. |
| isPrimary | Boolean | Yes | Whether this is the preferred contact point for its type. |
| notificationsEnabled | Boolean | Yes | Whether this contact point may receive notifications. |
| region | String | Yes | Region hint for phone normalization. |

#### 400 Bad Request

Invalid request. Possible causes: • A required field (type, value) is missing, blank, or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or contact point not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001/contact/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'
```

## PATCH /v3/patient/{patientId}/contact/{contactId}

Partially update a patient contact point

### Overview

Updates only the fields sent in the request body. Fields that are omitted or sent as null are left unchanged.

### 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. |
| contactId | Long | Yes | The ID of the contact point to partially update. |

### Request Body

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

```json
{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | Cannot be cleared. | The type of contact point. Cannot be cleared. |
| value | string | Yes | Cannot be cleared. | The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100). |
| label | string | No | Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |
| isPrimary | boolean | No | Only one contact point per type can be primary at a time. | Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary. |
| notificationsEnabled | boolean | No | Defaults to `false`. | Whether this contact point may receive notifications. Defaults to `false`. |
| region | string | No | Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). | Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`). |

### Responses

#### 200 OK

Contact point partially updated successfully.

**DTO**: `PatientContactResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Contact point record ID. |
| type | String | Yes | The type of contact point. |
| value | String | Yes | The address or number for this contact point. |
| label | String | Yes | Free-text label for this contact point. |
| isPrimary | Boolean | Yes | Whether this is the preferred contact point for its type. |
| notificationsEnabled | Boolean | Yes | Whether this contact point may receive notifications. |
| region | String | Yes | Region hint for phone normalization. |

#### 400 Bad Request

Invalid request. Possible causes: • A required field (type, value) sent blank or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or contact point not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/contact/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'
```

## DELETE /v3/patient/{patientId}/contact/{contactId}

Deactivate a patient contact point

### Overview

Soft-deletes a contact point. The record is deactivated but preserved for outreach history.

### 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. |
| contactId | Long | Yes | The ID of the contact point to deactivate. |

### Responses

#### 200 OK

Contact point deactivated successfully.

**DTO**: `PatientContactDeleteResponseDTO`

```json
{
  "id": 1001,
  "active": true,
  "deletedAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | The ID of the deactivated contact point. |
| active | boolean | No | Whether the contact point is active. |
| deletedAt | LocalDateTime | No | Timestamp when the contact point was deactivated. |

#### 400 Bad Request

Cannot delete a primary contact point — promote another of the same type first.

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or contact point not found.

#### 500 Internal Server Error

Unexpected error while processing the contact point request.

### Example

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