UiPath Documentation
activities
latest
false
Integration Service activities

Patient.$match

Patient.$match activity for Epic FHIR, finding the one patient that matches the supplied demographics, and the outcome codes Epic returns.

Project compatibility​

Windows | Cross-platform

Overview​

DescriptionAPI MethodAPI Path
Find the one patient matching the supplied demographics. Returns a single patient, or an empty record when none matched with certainty.GET/PatientMatch

Input​

Epic requires a minimum data set before it returns a patient, and each Epic organization configures its own. By default, one of the following is enough: an identifier on its own, Given Name with Family Name and Date of Birth, or Given Name with Family Name, Legal Sex and either Phone or Email. See The minimum data set and confirm what your organization accepts.

No single field is required, and Epic decides whether the combination you supply is sufficient. A request carrying no values at all is refused, because Epic answers an empty match with a no-results response that cannot be told apart from a genuine no-match.

ParameterDescriptionData Type
Given NameThe patient first (given) name.string
Family NameThe patient last (family) name.string
Date of BirthThe patient date of birth as YYYY-MM-DD.string
Legal SexThe patient legal sex: male, female, other or unknown.string
Identifier SystemThe identifier system that Identifier Value belongs to, such as the object identifier (OID) of your organization MRN. This value differs at every Epic organization, so confirm it with your Epic contact rather than copying one from Epic documentation or a sandbox. Epic ignores an identifier whose system it does not match on.string
Identifier ValueAn identifier for the patient, such as an MRN or national ID. On its own this satisfies one of Epic default minimum data sets, and it is the strongest single discriminator available. Supply Identifier System with it where you know it.string
PhoneA phone number on the patient record. With Given Name, Family Name and Legal Sex this satisfies one of Epic default minimum data sets.string
EmailAn email address on the patient record. With Given Name, Family Name and Legal Sex this satisfies one of Epic default minimum data sets.string
Address LineThe patient street address. Narrows a match that is otherwise uncertain.string
CityThe patient city. Narrows a match that is otherwise uncertain.string
StateThe patient state. Narrows a match that is otherwise uncertain.string
Postal CodeThe patient postal code. Narrows a match that is otherwise uncertain.string
CountryThe patient country. Narrows a match that is otherwise uncertain.string

Output​

content carries the matched patient record, and pagination reports whether anything matched.

Patient record​

ParameterDescriptionData Type
ActiveWhether the patient record is active.boolean
AddressThe patient's current address, as well as any previous or temporary addresses, if applicable. The patient's current address has a use code of " home ". If the patient also has one or more previous addresses, each previous address has a use code of " old ". The patient's temporary address has a use code of " temp ".Object
Address > CityThe city that the patient lives in.string
Address > CountryThe country that the patient lives in.string
Address > DistrictThe county that the patient lives in.string
Address > LineThe patient’s street address.string
Address > PeriodThe start date – and optionally, end date – for when the address is valid. Returned for the current address if the information is available. Starting in the May 2025 version of Epic, also returned for previous and temporary addresses if the information is available.Object
Address > Postal CodeThe patient’s postal code.string
Address > StateThe state where the patient lives.string
Address > TextThe patient’s full address as a string. This is formatted based on the country the address is in. For U.S. addresses, to meet the standards laid out in the Project US@ Technical Specifications , patient addresses format automatically for patient matching purposes.string
Address > UseSpecifies the type of address: home for a permanent address, old for a previous permanent address, or temp for a temporary address. Temporary addresses are returned according to the Epic organization's version and configuration.string
Birth DateThe patient's date of birth in the format YYYY-MM-DDstring
CommunicationLanguages used to communicate with the patient, along with an indicator of which is preferred.Object
Communication > LanguageThe patient's general language, onsite care language, and spoken language.Object
Communication > PreferredWhether the language is the patient's preferred language.boolean
ContactDetails for the patient's contacts. Patient contacts include any documented family members, emergency contacts, care givers, acquaintances, and employers.Object
Contact > AddressThe contact address. For responses to a patient-facing application, this element is not returned for contacts linked to a patient record. For organizations in the Netherlands, this element represents an nl-core-address value.Object
Contact > NameThe contact's preferred name. The system determines this from the contact's linked patient record if available. For contacts linked to a patient record, only the patient's official first name is returned in patient context. For organizations in the Netherlands, this element represents an nl-core-humanname value.Object
Contact > OrganizationAn Organization reference that represents the patient's employer. Returned when contact.relationship.code is E.Object
Contact > PeriodThe start and end dates for the patient contact.Object
Contact > RelationshipThe contact's relationship to the patient. This element can contain multiple Epic category values and, for organizations in the Netherlands, relationship or role code-system values.Object
Contact > TelecomTelephone numbers and email address for the contact. For responses to a patient-facing application, this element is not returned for contacts linked to a patient record. For organizations in the Netherlands, this element represents an nl-core-contactpoint value.Object
Contact > Telecom > RankThe priority for permanent phone numbers or emails. 1 indicates the highest priority phone number, 2 indicates the second priority, and so on. Starting in the May 2025 version of Epic, rank is returned for the phone numbers of patient contacts.string
Contact > Telecom > SystemThe type of telecom. Potential values are: email phonestring
Contact > Telecom > UseIf the telecom entry is a phone number, possible values are: home mobile workstring
Contact > Telecom > ValueValue of the telecom method. Can be an email address or phone number.string
Deceased BooleanWhether the patient is deceased.boolean
Deceased Date TimeThe date and time of death.string
ExtensionA reference to a newborn’s birth facility. URL: http://open.epic.com/FHIR/StructureDefinition/extension/birth-locationObject
GenderThe patient's legal sex.string
General PractitionerThe patient's Primary Care Provider (PCP). Reference to a Practitioner resource. For organizations in UK with EPS enabled at the system level, also contains an identifier-based reference to the patient's care organization.Object
IdThe Patient FHIR ID.string
IdentifierThe patient's identifiers. Includes the following: MPI IDs (such as MRNs) Epic MyChart login IDs Epic database IDs Payer Member IDs National IDs FHIR ID Care Everywhere ID For organizations in Singapore, the patient’s document ID, type, and expiry date.Object
Identifier > PeriodThe expiration date of the patient's identification document in Singapore. [R4 only]Object
Identifier > SystemThe namespace for the identifier, such as an Epic identity ID, MyChart ID, Care Everywhere ID, internal or external Epic ID, payer member ID, or national identifier.string
Identifier > TypeThe patient's identifier type. In Singapore, this is the patient's identification document type.Object
Identifier > Type > CodingThe type coding. [R4 only]Object
Identifier > Type > Coding > CodeThe type code. Epic external ID "um" Payer Member ID "MB" Australian Medicare Number "MC" [R4 only]string
Identifier > Type > Coding > SystemThe code system. Epic external ID http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType Payer Member ID http://terminology.hl7.org/CodeSystem/v2-0203 Australian Medicare Number http://terminology.hl7.org/CodeSystem/v2-0203 [R4 only]string
Identifier > ValueThe patient's ID. For organizations in Singapore, this can also be the patient's identification document ID.string
LinkContains links to other patient records if the patient record was involved in a merge. Each link element represents a single merge event. If the patient was involved in multiple merges, multiple Link elements are returned. Starting in the February 2024 version of Epic, the 30 most recent merge events are returned instead of all merge events.Object
Link > OtherA Patient reference to the source patient. In a merge, the source patient is the patient that goes away.Object
Link > Other > ReferenceA reference to the Patient resource that this Patient replaces. [STU3 only]string
Link > TypeThe type of link between Patient resources. This is always set to " replaces ". The Patient FHIR ID in the link.extension (patient-merge-target-reference) element replaces the Patient FHIR ID referenced in the link.other element.string
Managing OrganizationThe patient’s primary service area. Reference to an Organization resource.Object
Marital StatusThe patient's marital status.Object
MetaMetadata about the resource.Object
Meta > ProfileOnly returned for organizations in the Netherlands. This element shows that this API conforms to the profile connected to the following canonical url: http://fhir.nl/fhir/StructureDefinition/nl-core-patient [STU3 only]string
Meta > SecurityThe patient's unverified status. For unverified patients, this element indicates that the record may need reconciliation and includes the PATRPT (Patient Reported) value; it is not returned for verified patients.Object
Multiple Birth IntegerThe patient's birth order.int32
NameThe patient's name.Object
Name > FamilyThe patient's family (last) name. Can contain a data-absent-reason extension with a value of " unknown " if the patient has an alias that cannot be returned as discrete elements or if the patient's preferred name replaces their full name.string
Name > GivenThe patient's given name. Can include first and middle names.string
Name > PrefixThe patient's name prefix.string
Name > SuffixThe patient's name suffix. Acquired as a title due to academic, legal, employment or nobility status, etc.string
Name > TextThe patient's full name as a string.string
Name > UseThe purpose of the name. Can be "official", "usual", or "old".string
Resource TypeThe FHIR resource type (always "Patient" for this activity).string
TelecomTelephone numbers and email addresses for the patient, along with their use (home or work for example) and their preferred rank (which to contact first, second, third, etc).Object
Telecom > RankThe priority for permanent phone numbers or emails. 1 indicates the highest priority phone number, 2 indicates the second priority, etc . The preferred has a rank of 1. Additional emails have a null rank.string
Telecom > SystemThe type of telecom. Potential values are: email phone fax url pager sms otherstring
Telecom > UseIf the telecom entry is a phone number, possible values are: home mobile work temp old Use is not returned for emails.string
Telecom > ValueValue of the telecom method. Can be an email address or phone number.string

Pagination​

ParameterDescriptionData Type
Has More PagesAlways false. Patient Match resolves to at most one patient, so there is never a further page.boolean
Next Page Session IdAlways empty. Patient Match resolves to at most one patient, so there is no continuation token.string
Returned Count1 when a patient matched, 0 when none did. Epic returns a patient only when it is certain, so this is never more than 1.int32
Note:
  • In API workflows, a single response object is returned as the output. Any required fields can be extracted directly from this object.
  • In RPA workflows, some output parameters may differ, but the necessary values can still be retrieved from the response object even if they are not explicitly exposed.

How the match works​

The activity wraps Epic's Patient.$match (R4) operation. Epic's implementation requires onlyCertainMatches = true, which the connector always sets. Epic returns a patient only when it is confident the demographics identify exactly one person, so the activity returns at most one record and is not a way to retrieve more than one patient.

For the choice between this activity and a patient search, see Finding a patient.

Epic reports the confidence of the match through an outcome code:

OutcomeEpic codeMeaning
One patient returnedNoneThe match succeeded.
Multiple high-confidence matches59011The request needs a discriminator, and Identifier Value is the strongest. Falling back to a search and taking the first result is unsafe.
Only low-confidence matches59013A discriminator is missing or incorrect. The response is not a match, and this is the outcome callers hit most often.
No matches4101A valid answer rather than an error. The activity returns an empty record, so an empty Id means no patient matched.

Two behaviors the connector handles for you​

  • Phone numbers require a use value. Epic rejects a phone number submitted without a use value of home, work or mobile. It discards the number and then reports that it could not reach certainty, having removed the detail that would have provided it. The connector always supplies a use value. Testing showed the specific value has no effect on the result, which is why Phone is a single field rather than a number and a separate classification.
  • Rejected values produce a clear error. Epic reports any value it cannot use as code 59109 and then completes the match without it, which quietly weakens your request. The connector fails the activity when a value was rejected and no patient matched, and it includes Epic's own diagnostics where they are available. A rejected value is not reported as a missing patient.
  • Finding a patient — choosing between Patient.$match and a patient search, and the minimum data set Epic requires.
  • Patient.$summary — retrieving a matched patient's clinical summary from the FHIR ID this activity returns.
  • Epic FHIR authentication — setting up the connection this activity uses.

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated