This article provides in-depth advice over how to use record identifiers with the Identity API.
Contents
When adding records using the Identity API, you provide a source name and source-specific record identifier. For example, when adding John Smith’s record from Community Clinic, you might use source name CommunityClinic
and Community’s internal database id 12345
:
POST /mpi/v1/record/CommunityClinic/12345
{
"firstName":"John",
"lastName":"Smith",
"dob":"1/2/2003",
...
}
These record identifiers are also returned, in plain text, when you query for patients. For example, if you try to find records matching John’s demographics, you would receive:
{
"matchedPerson": {
"id": "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0",
"records": [
{
"source": "CommunityClinic",
"identifier": "12345"
}
],
...
}
Identifiers come in two basic types:
Internal identifiers are preferable for several reasons:
Selecting the appropriate source identifier requires knowledge of the source system. You want one that is:
For example, a HL7 system might send multiple identifiers in PID.3
:
PID|1||111111^^^AA1^MR^ABC~123456789^^^SSA^SS^ABC~12345^^^AA2^PI^ABC||Smith^John|||||||||||||7890
The identifiers include:
MR
) of 111111 from assigning authority “AA1”.SS
) of 123-45-6789 from assigning authority “SSA”.PI
) of 12345 from assigning authority “AA2”.If you know that this system reliably sends the PI
identifier type for every record, that would probably be your best candidate.
For a FHIR-based source system, you would similarly need to select from among the various identifiers in the Patient.identifier
field:
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR"
}
]
},
"value": "11111",
...
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "PI"
}
]
},
"value": "12345",
...
},
]
As with the HL7 message, the identifier of type PI
(for internal patient identifier) is likely the one you should use.
This section describes a few special cases that you should consider when sending record identifiers to the Identity API.
If you do not wish the Identity service to ever receive plain-text record identifiers, you can encrypt all source identifiers before sending them, and decrypt them in any query response.
In the unlikely event that your source system has no suitable internal identifier, you may consider creating your own synthetic one. You would need to manage a mapping table that translates your synthetic identifiers to their original source ones.
For example, assume a HL7 source system (Community Clinic) only provides an account number (business identifier). You might receive a few record updates:
PID|1||111111^^^AA1^AN^ABC~12345^^^AA2^MR^ABC|Smith^John|||||||||||||7890
PID|1||111111^^^AA1^AN^ABC|Smith^John|||||||||||||7890
PID|1||222222^^^AA1^AN^ABC~12345^^^AA2^MR^DEF|Jones^Mary|||||||||||||7890
Your mapping table for synthetic identifiers would then be:
Synthetic Internal ID | Source System | Source Identifier |
1 | CommunityClinic | AA1-111111 |
2 | CommunityClinic | AA1-222222 |
Any time your system received a message from Community Clinic for John (account number AA1-111111), you would send CommunityClinic
and 1
as the source system and identifier. Any time you received a message from Community Clinic for Mary (account number AA1-222222), you would send CommunityClinic
and 2
.
When matching patients, the Identity service will return these synthetic IDs:
{
"matchedPerson": {
"id": "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0",
"records": [
{
"source": "CommunityClinic",
"identifier": "1"
}
],
...
}
You would then use your mapping table to determine that CommunityClinic
identifier 1
was associated with account number AA1-111111.