Identifier
/v3/patient/{patientId}/identifier endpoint reference.
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.
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
{
"identifiers": [
{}
]
}
| Field | Type | Nullable | Description |
|---|---|---|---|
| identifiers | List | 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
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.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| patientId | Long | Yes | The ID of the patient. |
Request Body
Content-Type: application/json · DTO: PatientIdentifierRequestDTO
{
"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- | |
| 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
{
"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
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.
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
{
"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
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.
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
{
"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- | |
| 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
{
"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
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.
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
{
"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- | |
| 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
{
"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
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.
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
{
"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
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