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

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

APIs for managing patient name aliases. Supports creating, listing, updating, and deactivating alternate name records (maiden names, nicknames, legal changes, etc.).

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/alias | GET | List patient name aliases |
| /v3/patient/{patientId}/alias | POST | Add a new name alias to a patient |
| /v3/patient/{patientId}/alias/{aliasId} | GET | Get a specific patient name alias |
| /v3/patient/{patientId}/alias/{aliasId} | PUT | Fully update a patient name alias |
| /v3/patient/{patientId}/alias/{aliasId} | PATCH | Partially update a patient name alias |
| /v3/patient/{patientId}/alias/{aliasId} | DELETE | Deactivate a patient name alias |

---

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

List patient name aliases

### Overview

Returns all active name aliases for a patient. Returns an array of alias records (possibly empty). Only active (non-deleted) aliases are returned.

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

### Responses

#### 200 OK

List of patient name aliases.

**DTO**: `PatientAliasListResponseDTO`

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

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| aliases | List<PatientAliasResponseDTO> | No | List of name alias records. |

#### 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/alias" \
  -H "Authorization: Bearer $TOKEN"
```

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

Add a new name alias to a patient

### Overview

Creates a new name alias record for a patient. Used to track alternate names such as maiden names, nicknames, legal name changes, or preferred names. Creates a new alias record — existing aliases are not modified. At least one of `alias`, `firstName`, `lastName`, or `fullName` must be provided. `type` is required and must be one of: `maiden`, `nickname`, `preferred`, `previous`, `legal_change`, `alias`. Requires authentication.

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

### Request Body

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

```json
{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | allowableValues: maiden, nickname, preferred, previous, legal_change, alias | Type of name alias. |
| alias | string | No |  | Alias or nickname. |
| firstName | string | No |  | Alternate first name. |
| lastName | string | No |  | Alternate last name. |
| fullName | string | No |  | Full alternate name for mononyms or cultural formats. |
| effectiveFrom | string | No | format: date | When this name was in use in YYYY-MM-DD format. |
| effectiveTo | string | No | format: date | When this name stopped being used in YYYY-MM-DD format. |

### Responses

#### 201 Created

Alias created successfully.

**DTO**: `PatientAliasResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Alias record ID. |
| type | String | No | Type of name alias. |
| alias | String | Yes | Alias or nickname. |
| firstName | String | Yes | Alternate first name. |
| lastName | String | Yes | Alternate last name. |
| fullName | String | Yes | Full alternate name. |
| effectiveFrom | LocalDate | Yes | When this name was in use. |
| effectiveTo | LocalDate | Yes | When this name stopped being used. |

#### 400 Bad Request

Invalid request. Possible causes: Missing required field (type), No name field provided (alias, firstName, lastName, or fullName), Invalid type value, 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/alias" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

## GET /v3/patient/{patientId}/alias/{aliasId}

Get a specific patient name alias

### Overview

Returns a single name alias record for a patient. Requires authentication. Returns 404 if the alias 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. |
| aliasId | Long | Yes | The ID of the alias record. |

### Responses

#### 200 OK

Alias record found.

**DTO**: `PatientAliasResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Alias record ID. |
| type | String | No | Type of name alias. |
| alias | String | Yes | Alias or nickname. |
| firstName | String | Yes | Alternate first name. |
| lastName | String | Yes | Alternate last name. |
| fullName | String | Yes | Full alternate name. |
| effectiveFrom | LocalDate | Yes | When this name was in use. |
| effectiveTo | LocalDate | Yes | When this name stopped being used. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

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

### Example

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

## PUT /v3/patient/{patientId}/alias/{aliasId}

Fully update a patient name alias

### Overview

Replaces all fields of an existing alias record. The `type` field and at least one name field are required. All required fields must be present in the request. Fields not provided will be cleared. Requires authentication. Returns 404 if the alias 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. |
| aliasId | Long | Yes | The ID of the alias record to update. |

### Request Body

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

```json
{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | allowableValues: maiden, nickname, preferred, previous, legal_change, alias | Type of name alias. |
| alias | string | No |  | Alias or nickname. |
| firstName | string | No |  | Alternate first name. |
| lastName | string | No |  | Alternate last name. |
| fullName | string | No |  | Full alternate name for mononyms or cultural formats. |
| effectiveFrom | string | No | format: date | When this name was in use in YYYY-MM-DD format. |
| effectiveTo | string | No | format: date | When this name stopped being used in YYYY-MM-DD format. |

### Responses

#### 200 OK

Alias updated successfully.

**DTO**: `PatientAliasResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Alias record ID. |
| type | String | No | Type of name alias. |
| alias | String | Yes | Alias or nickname. |
| firstName | String | Yes | Alternate first name. |
| lastName | String | Yes | Alternate last name. |
| fullName | String | Yes | Full alternate name. |
| effectiveFrom | LocalDate | Yes | When this name was in use. |
| effectiveTo | LocalDate | Yes | When this name stopped being used. |

#### 400 Bad Request

Invalid request. Possible causes: Missing required field (type), No name field provided (alias, firstName, lastName, or fullName), Invalid type value, Invalid date format for effectiveFrom or effectiveTo, effectiveTo is before effectiveFrom

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or alias not found.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001/alias/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

## PATCH /v3/patient/{patientId}/alias/{aliasId}

Partially update a patient name alias

### Overview

Updates only the fields provided in the request body. Fields not included are left unchanged. Only non-null fields are applied. Existing values for omitted fields are preserved. Requires authentication. Returns 404 if the alias 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. |
| aliasId | Long | Yes | The ID of the alias record to partially update. |

### Request Body

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

```json
{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | allowableValues: maiden, nickname, preferred, previous, legal_change, alias | Type of name alias. |
| alias | string | No |  | Alias or nickname. |
| firstName | string | No |  | Alternate first name. |
| lastName | string | No |  | Alternate last name. |
| fullName | string | No |  | Full alternate name for mononyms or cultural formats. |
| effectiveFrom | string | No | format: date | When this name was in use in YYYY-MM-DD format. |
| effectiveTo | string | No | format: date | When this name stopped being used in YYYY-MM-DD format. |

### Responses

#### 200 OK

Alias partially updated successfully.

**DTO**: `PatientAliasResponseDTO`

```json
{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Alias record ID. |
| type | String | No | Type of name alias. |
| alias | String | Yes | Alias or nickname. |
| firstName | String | Yes | Alternate first name. |
| lastName | String | Yes | Alternate last name. |
| fullName | String | Yes | Full alternate name. |
| effectiveFrom | LocalDate | Yes | When this name was in use. |
| effectiveTo | LocalDate | Yes | When this name stopped being used. |

#### 400 Bad Request

Invalid request. Possible causes: Invalid type value, Invalid date format for effectiveFrom or effectiveTo, effectiveTo is before effectiveFrom

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or alias not found.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/alias/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'
```

## DELETE /v3/patient/{patientId}/alias/{aliasId}

Deactivate a patient name alias

### Overview

Soft-deletes an alias record. The alias is deactivated but preserved for audit trail. Requires authentication. Returns 404 if the alias 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. |
| aliasId | Long | Yes | The ID of the alias record to deactivate. |

### Responses

#### 200 OK

Alias deactivated successfully.

**DTO**: `PatientAliasDeleteResponseDTO`

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

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

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

Patient or alias not found.

### Example

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