Identifier
/v3/patient/{patientId}/identifier endpoint reference.
URL: https://demo.1health.io/api/v3/patient/{patientId}/identifier
APIs for managing a patient's external identifiers. Supports adding, listing, fetching, replacing, amending, and deactivating identifiers that link a patient to records in external systems. Multi-tenant administrators operate across all tenants (reading and writing identifiers regardless of owning tenant); other users are scoped to their own tenant.
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. To deactivate, set active_until to the deactivation timestamp. 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. The (organization, external system) cross-reference is preserved on the record for history and dedup audit. 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