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

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

REST API for managing a patient's external identifiers in the Patient Vault. An identifier is an (authority organization + external system) pair, keyed in the URL by their ids. The identifier value is kept out of the URL to avoid logging PII. This is a simplified repackaging of the External System mapping API.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/identifier | GET | List a patient's external identifiers |
| /v3/patient/{patientId}/identifier | POST | Add an external identifier to a patient |
| /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId} | GET | Get a single patient external identifier |
| /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId} | PUT | Fully update a patient external identifier |
| /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId} | PATCH | Partially update a patient external identifier |
| /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId} | DELETE | Deactivate a patient external identifier |

---

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

List a patient's external identifiers

### Overview

Returns all external identifiers for a patient. 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. |

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| active | String | No | true | Filter by activation state: true (default, active only), false (deactivated only), all. |

### Responses

#### 200 OK

List of patient external identifiers.

**DTO**: `PatientIdentifierListResponseDTO`

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

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| identifiers | List<PatientIdentifierResponseDTO> | No | The patient's external identifier records. |

#### 400 Bad Request

Invalid active value — allowed values are true, false, all.

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

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

Add an external identifier to a patient

### Overview

Appends a new external identifier to a patient, recorded as an (authority organization + external system) pair. 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. |

### Request Body

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

```json
{
  "value": "example-value",
  "type": "example-value",
  "authority_organization_id": "example-value",
  "authority_organization_name": "example-value",
  "authority_external_system_id": "example-value",
  "authority_external_system_name": "example-value",
  "source_name": "example-value",
  "active_from": "example-value",
  "active_until": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| value | string | Yes |  | The identifier value itself — the id of the patient record in the external system. |
| type | string | No |  | Identifier type label — e.g. mrn, member_id, ssn, npi, passport, driver_license, custom. |
| authority_organization_id | integer | No |  | ID of the organization that issued the identifier (the organization that owns the external system). Mutually exclusive with authority_organization_name — providing both is rejected. If neither id nor name is provided, the caller's context organization is used. If an id is provided but does not exist, the request fails. |
| authority_organization_name | string | No |  | Name of the organization that issued the identifier. Mutually exclusive with authority_organization_id — providing both is rejected. If the name does not match an existing organization, a new tenant (and its organization) is provisioned and linked. |
| authority_external_system_id | integer | No |  | ID of the external system. Mutually exclusive with authority_external_system_name — providing both is rejected. If neither id nor name is provided, a unique 'Unknown-<uuid>' placeholder system is created per identifier. If an id is provided but does not exist, the request fails. |
| authority_external_system_name | string | No |  | Name of the external information system (e.g. "Epic", "Cerner"). Mutually exclusive with authority_external_system_id — providing both is rejected. If the name does not match an existing system, one is created and linked. |
| source_name | string | No |  | Where this identifier came from — e.g. "payer feed", "manual entry", "ADT import". |
| active_from | string | No |  | When this identifier became active, as an ISO-8601 instant; stored as UTC. Null = active since record creation. Accepts offset/Z (2024-01-01T00:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |
| active_until | string | No |  | When this identifier expires or was deactivated, as an ISO-8601 instant; stored as UTC. Null = currently active. Accepts offset/Z (2026-05-14T09:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |

### Responses

#### 201 Created

Identifier added successfully.

**DTO**: `PatientIdentifierResponseDTO`

```json
{
  "id": 1001,
  "organization_id": 1001,
  "organization_name": "example-value",
  "external_system_id": 1001,
  "external_system_name": "example-value",
  "value": "example-value",
  "type": "example-value",
  "source_name": "example-value",
  "active_from": "2024-01-15T09:30:00Z",
  "active_until": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the identifier (external system mapping) record. |
| organization_id | Long | Yes | ID of the organization that issued the identifier. |
| organization_name | String | Yes | Name of the organization that issued the identifier. |
| external_system_id | Long | Yes | ID of the external system. |
| external_system_name | String | Yes | Name of the external system. |
| value | String | Yes | The identifier value in the external system. |
| type | String | Yes | Identifier type label. |
| source_name | String | Yes | Where this identifier came from. |
| active_from | LocalDateTime | Yes | When this identifier became active (UTC). Null = active since record creation. |
| active_until | LocalDateTime | Yes | When this identifier expires or was deactivated (UTC). Null = currently active. |

#### 400 Bad Request

Invalid request. Possible causes: Missing required field (value), Both an id and a name were provided for the authority organization or external system, Neither an authority organization id nor name was provided and the current tenant has no context organization, Referenced authority_organization_id or authority_external_system_id does not exist, An identifier with this (organization, external system) pair already exists for this patient, Invalid active_from / active_until timestamp, active_until is before active_from

#### 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/identifier" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"value": "example-value", "type": "example-value", "authority_organization_id": "example-value", "authority_organization_name": "example-value", "authority_external_system_id": "example-value", "authority_external_system_name": "example-value", "source_name": "example-value", "active_from": "example-value", "active_until": "example-value"}'
```

## GET /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId}

Get a single patient external identifier

### Overview

Returns one external identifier by its (organization, external system) pair. 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. |
| organizationId | Long | Yes | The ID of the authority organization. |
| externalSystemId | Long | Yes | The ID of the external system. |

### Responses

#### 200 OK

Identifier found.

**DTO**: `PatientIdentifierResponseDTO`

```json
{
  "id": 1001,
  "organization_id": 1001,
  "organization_name": "example-value",
  "external_system_id": 1001,
  "external_system_name": "example-value",
  "value": "example-value",
  "type": "example-value",
  "source_name": "example-value",
  "active_from": "2024-01-15T09:30:00Z",
  "active_until": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the identifier (external system mapping) record. |
| organization_id | Long | Yes | ID of the organization that issued the identifier. |
| organization_name | String | Yes | Name of the organization that issued the identifier. |
| external_system_id | Long | Yes | ID of the external system. |
| external_system_name | String | Yes | Name of the external system. |
| value | String | Yes | The identifier value in the external system. |
| type | String | Yes | Identifier type label. |
| source_name | String | Yes | Where this identifier came from. |
| active_from | LocalDateTime | Yes | When this identifier became active (UTC). Null = active since record creation. |
| active_until | LocalDateTime | Yes | When this identifier expires or was deactivated (UTC). Null = currently active. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

No identifier found for that (organization, external system) pair.

### Example

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

## PUT /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId}

Fully update a patient external identifier

### Overview

Replaces the mutable fields (value, type, source_name, active_from, active_until) of an identifier. The (organization, external system) pair is fixed by the URL. 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. |
| organizationId | Long | Yes | The ID of the authority organization. |
| externalSystemId | Long | Yes | The ID of the external system. |

### Request Body

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

```json
{
  "value": "example-value",
  "type": "example-value",
  "authority_organization_id": "example-value",
  "authority_organization_name": "example-value",
  "authority_external_system_id": "example-value",
  "authority_external_system_name": "example-value",
  "source_name": "example-value",
  "active_from": "example-value",
  "active_until": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| value | string | Yes |  | The identifier value itself — the id of the patient record in the external system. |
| type | string | No |  | Identifier type label — e.g. mrn, member_id, ssn, npi, passport, driver_license, custom. |
| authority_organization_id | integer | No |  | ID of the organization that issued the identifier (the organization that owns the external system). Mutually exclusive with authority_organization_name — providing both is rejected. If neither id nor name is provided, the caller's context organization is used. If an id is provided but does not exist, the request fails. |
| authority_organization_name | string | No |  | Name of the organization that issued the identifier. Mutually exclusive with authority_organization_id — providing both is rejected. If the name does not match an existing organization, a new tenant (and its organization) is provisioned and linked. |
| authority_external_system_id | integer | No |  | ID of the external system. Mutually exclusive with authority_external_system_name — providing both is rejected. If neither id nor name is provided, a unique 'Unknown-<uuid>' placeholder system is created per identifier. If an id is provided but does not exist, the request fails. |
| authority_external_system_name | string | No |  | Name of the external information system (e.g. "Epic", "Cerner"). Mutually exclusive with authority_external_system_id — providing both is rejected. If the name does not match an existing system, one is created and linked. |
| source_name | string | No |  | Where this identifier came from — e.g. "payer feed", "manual entry", "ADT import". |
| active_from | string | No |  | When this identifier became active, as an ISO-8601 instant; stored as UTC. Null = active since record creation. Accepts offset/Z (2024-01-01T00:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |
| active_until | string | No |  | When this identifier expires or was deactivated, as an ISO-8601 instant; stored as UTC. Null = currently active. Accepts offset/Z (2026-05-14T09:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |

### Responses

#### 200 OK

Identifier updated successfully.

**DTO**: `PatientIdentifierResponseDTO`

```json
{
  "id": 1001,
  "organization_id": 1001,
  "organization_name": "example-value",
  "external_system_id": 1001,
  "external_system_name": "example-value",
  "value": "example-value",
  "type": "example-value",
  "source_name": "example-value",
  "active_from": "2024-01-15T09:30:00Z",
  "active_until": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the identifier (external system mapping) record. |
| organization_id | Long | Yes | ID of the organization that issued the identifier. |
| organization_name | String | Yes | Name of the organization that issued the identifier. |
| external_system_id | Long | Yes | ID of the external system. |
| external_system_name | String | Yes | Name of the external system. |
| value | String | Yes | The identifier value in the external system. |
| type | String | Yes | Identifier type label. |
| source_name | String | Yes | Where this identifier came from. |
| active_from | LocalDateTime | Yes | When this identifier became active (UTC). Null = active since record creation. |
| active_until | LocalDateTime | Yes | When this identifier expires or was deactivated (UTC). Null = currently active. |

#### 400 Bad Request

Invalid request. Possible causes: Missing required field (value), Invalid active_from / active_until timestamp, active_until is before active_from

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

No identifier found for that (organization, external system) pair.

### Example

```bash
curl -X PUT "https://demo.1health.io/api/v3/patient/1001/identifier/1001/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"value": "example-value", "type": "example-value", "authority_organization_id": "example-value", "authority_organization_name": "example-value", "authority_external_system_id": "example-value", "authority_external_system_name": "example-value", "source_name": "example-value", "active_from": "example-value", "active_until": "example-value"}'
```

## PATCH /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId}

Partially update a patient external identifier

### Overview

Updates only the fields provided in the request body. Fields not included are left unchanged. 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. |
| organizationId | Long | Yes | The ID of the authority organization. |
| externalSystemId | Long | Yes | The ID of the external system. |

### Request Body

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

```json
{
  "value": "example-value",
  "type": "example-value",
  "authority_organization_id": "example-value",
  "authority_organization_name": "example-value",
  "authority_external_system_id": "example-value",
  "authority_external_system_name": "example-value",
  "source_name": "example-value",
  "active_from": "example-value",
  "active_until": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| value | string | Yes |  | The identifier value itself — the id of the patient record in the external system. |
| type | string | No |  | Identifier type label — e.g. mrn, member_id, ssn, npi, passport, driver_license, custom. |
| authority_organization_id | integer | No |  | ID of the organization that issued the identifier (the organization that owns the external system). Mutually exclusive with authority_organization_name — providing both is rejected. If neither id nor name is provided, the caller's context organization is used. If an id is provided but does not exist, the request fails. |
| authority_organization_name | string | No |  | Name of the organization that issued the identifier. Mutually exclusive with authority_organization_id — providing both is rejected. If the name does not match an existing organization, a new tenant (and its organization) is provisioned and linked. |
| authority_external_system_id | integer | No |  | ID of the external system. Mutually exclusive with authority_external_system_name — providing both is rejected. If neither id nor name is provided, a unique 'Unknown-<uuid>' placeholder system is created per identifier. If an id is provided but does not exist, the request fails. |
| authority_external_system_name | string | No |  | Name of the external information system (e.g. "Epic", "Cerner"). Mutually exclusive with authority_external_system_id — providing both is rejected. If the name does not match an existing system, one is created and linked. |
| source_name | string | No |  | Where this identifier came from — e.g. "payer feed", "manual entry", "ADT import". |
| active_from | string | No |  | When this identifier became active, as an ISO-8601 instant; stored as UTC. Null = active since record creation. Accepts offset/Z (2024-01-01T00:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |
| active_until | string | No |  | When this identifier expires or was deactivated, as an ISO-8601 instant; stored as UTC. Null = currently active. Accepts offset/Z (2026-05-14T09:00:00Z), zoneless (interpreted as UTC), or date-only (UTC start of day). |

### Responses

#### 200 OK

Identifier partially updated successfully.

**DTO**: `PatientIdentifierResponseDTO`

```json
{
  "id": 1001,
  "organization_id": 1001,
  "organization_name": "example-value",
  "external_system_id": 1001,
  "external_system_name": "example-value",
  "value": "example-value",
  "type": "example-value",
  "source_name": "example-value",
  "active_from": "2024-01-15T09:30:00Z",
  "active_until": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the identifier (external system mapping) record. |
| organization_id | Long | Yes | ID of the organization that issued the identifier. |
| organization_name | String | Yes | Name of the organization that issued the identifier. |
| external_system_id | Long | Yes | ID of the external system. |
| external_system_name | String | Yes | Name of the external system. |
| value | String | Yes | The identifier value in the external system. |
| type | String | Yes | Identifier type label. |
| source_name | String | Yes | Where this identifier came from. |
| active_from | LocalDateTime | Yes | When this identifier became active (UTC). Null = active since record creation. |
| active_until | LocalDateTime | Yes | When this identifier expires or was deactivated (UTC). Null = currently active. |

#### 400 Bad Request

Invalid request. Possible causes: Invalid active_from / active_until timestamp, Resulting active_until is before active_from

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

No identifier found for that (organization, external system) pair.

### Example

```bash
curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/identifier/1001/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"value": "example-value", "type": "example-value", "authority_organization_id": "example-value", "authority_organization_name": "example-value", "authority_external_system_id": "example-value", "authority_external_system_name": "example-value", "source_name": "example-value", "active_from": "example-value", "active_until": "example-value"}'
```

## DELETE /v3/patient/{patientId}/identifier/{organizationId}/{externalSystemId}

Deactivate a patient external identifier

### Overview

Soft-deletes an identifier: its active_until is set to the current timestamp and the record is marked deleted. 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. |
| organizationId | Long | Yes | The ID of the authority organization. |
| externalSystemId | Long | Yes | The ID of the external system. |

### Responses

#### 200 OK

Identifier deactivated successfully.

**DTO**: `PatientIdentifierDeleteResponseDTO`

```json
{
  "id": 1001,
  "organization_id": 1001,
  "organization_name": "example-value",
  "external_system_id": 1001,
  "external_system_name": "example-value",
  "active_until": "2024-01-15T09:30:00Z",
  "deletedAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | ID of the identifier (external system mapping) record. |
| organization_id | Long | Yes | ID of the organization that issued the identifier. |
| organization_name | String | Yes | Name of the organization that issued the identifier. |
| external_system_id | Long | Yes | ID of the external system. |
| external_system_name | String | Yes | Name of the external system. |
| active_until | LocalDateTime | Yes | When the identifier was deactivated (UTC). |
| deletedAt | LocalDateTime | Yes | Timestamp when the identifier was soft-deleted. |

#### 401 Unauthorized

Not authenticated — valid session required.

#### 404 Not Found

No identifier found for that (organization, external system) pair.

### Example

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