Patient $match

post/Patient/$match

Page View

This resource establishes demographics and identifiers for an individual visiting or receiving treatment from a healthcare organization. A patient record serves as the most common base for data being exchanged since it establishes the “who” behind the data.

You can review, retrieve, create, update, or match patient records.

Supported fields and schema examples

We support any valid FHIR® field. However, we only display fields we’ve defined in our schema, which are usually based on what’s included in the U.S. Core profile. We recommend relying on U.S. Core requirements.

Our schema examples show the shape and possibility of each FHIR® resource; they aren’t code for real-time API calls. We don’t currently recommend copying and pasting these schema examples for your API calls. Consider reviewing FHIR® API actions for realistic examples for particular use cases.

$match

Perform a demographics search for a patient using Verato's EMPI.

Based on the patient demographics provided, the response returns one or more potential matches of patient records from different systems within Verato's EMPI. You can select which patient record looks like a match to the patient you're searching for.

Request parameters and payload

cURL request example

bash

1
curl 'https://api.redoxengine.com/fhir/R4/{destinationSlug}/{environmentFlag}/Patient/$match' \
2
--request POST \
3
--header 'Authorization: Bearer $API_TOKEN' \
4
--header 'Content-Type: application/fhir+json' \
5
--data '{
6
  "id": "RedoxPatientMatchExample",
7
  "onlyCertainMatches": true,
8
  "count": 2,
9
  "matchScoreThreshold": 0.8,
10
  "resource": {
11
    "resourceType": "Patient",
12
    "id": "RedoxPatientExampleTimothyWrite",
13
    "extension": [
14
      {
15
        "extension": [
16
          {
17
            "url": "text",
18
            "valueString": "White"
19
          }
20
        ],
21
        "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
22
      },
23
      {
24
        "extension": [
25
          {
26
            "url": "ombCategory",
27
            "valueCoding": {
28
              "code": "2135-2",
29
              "system": "urn:oid:2.16.840.1.113883.6.238",
30
              "display": "Hispanic or Latino"
31
            }
32
          },
33
          {
34
            "url": "text",
35
            "valueString": "Hispanic"
36
          }
37
        ],
38
        "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity"
39
      }
40
    ],
41
    "name": [
42
      {
43
        "given": [
44
          "Timothy",
45
          "Paul"
46
        ],
47
        "family": "Bixby",
48
        "use": "official"
49
      },
50
      {
51
        "text": "Billy",
52
        "use": "usual"
53
      }
54
    ],
55
    "gender": "male",
56
    "birthDate": "2008-01-06",
57
    "telecom": [
58
      {
59
        "value": "+18088675301",
60
        "system": "phone",
61
        "use": "home"
62
      },
63
      {
64
        "value": "+18008675309",
65
        "system": "phone",
66
        "use": "work"
67
      },
68
      {
69
        "value": "timothy.bixby@redoxengine.com",
70
        "system": "email"
71
      }
72
    ],
73
    "address": [
74
      {
75
        "line": [
76
          "4762 Hickory Street"
77
        ],
78
        "city": "Monroe",
79
        "district": "Greene",
80
        "state": "WI",
81
        "postalCode": "53566",
82
        "country": "US",
83
        "use": "home"
84
      }
85
    ],
86
    "maritalStatus": {
87
      "coding": [
88
        {
89
          "code": "M",
90
          "system": "http://hl7.org/fhir/v3/MaritalStatus",
91
          "display": "Married"
92
        }
93
      ],
94
      "text": "Married"
95
    },
96
    "communication": [
97
      {
98
        "language": {
99
          "coding": [
100
            {
101
              "code": "en",
102
              "system": "urn:ietf:bcp:47"
103
            }
104
          ],
105
          "text": "English"
106
        }
107
      }
108
    ],
109
    "contact": [
110
      {
111
        "name": {
112
          "given": [
113
            "Barbara"
114
          ],
115
          "family": "Bixby"
116
        },
117
        "telecom": [
118
          {
119
            "value": "+18088675303",
120
            "system": "phone",
121
            "use": "home"
122
          },
123
          {
124
            "value": "barbara.bixby@redoxengine.com",
125
            "system": "email"
126
          }
127
        ],
128
        "address": {
129
          "line": [
130
            "4762 Hickory St."
131
          ],
132
          "city": "Monroe",
133
          "district": "Green",
134
          "state": "WI",
135
          "postalCode": "53566",
136
          "country": "USA"
137
        },
138
        "relationship": [
139
          {
140
            "coding": [
141
              {
142
                "code": "MTH",
143
                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
144
                "display": "mother"
145
              }
146
            ],
147
            "text": "Mother"
148
          },
149
          {
150
            "coding": [
151
              {
152
                "code": "C",
153
                "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
154
                "display": "Emergency Contact"
155
              }
156
            ],
157
            "text": "Emergency Contact"
158
          }
159
        ]
160
      }
161
    ],
162
    "generalPractitioner": [
163
      {
164
        "reference": "Practitioner/RedoxPractitionerExamplePat"
165
      }
166
    ],
167
    "managingOrganization": {
168
      "reference": "Organization/RedoxOrganizationManagingExample"
169
    },
170
    "identifier": [
171
      {
172
        "value": "0000000001",
173
        "type": {
174
          "text": "MR"
175
        }
176
      }
177
    ]
178
  }
179
}'

Request Body Schema

Redox Patient Match operation

resource
required, object
The Patient Resource.
- resourceType
  required, string
  Identifies the type of the resource
  Value: Patient
- identifier
  required, Array of object
  An identifier for this patient.
  system
  required, string
  Establishes the namespace for the value - that is, a URL that describes a set values that are unique.
  value
  required, string
  The portion of the identifier typically relevant to the user and which is unique within the context of the system.
  extension
  Array of Boolean, String, CodeableConcept, Coding
  May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.
  One of:
  url
  required, string
  Source of the definition for the extension code - a logical name or a URL.
  valueBoolean
  boolean
  A single value for the extension.
  use
  string
  The purpose of this identifier.
  Possible Values: usual, official, temp, secondary, old (If known)
- name
  required, Array of object
  A name associated with the individual.
  family
  string
  The part of a name that links to the genealogy. In some cultures (e.g. Eritrea) the family name of a son is the first name of his father.
  given
  Array of string
  Given name.
  use
  string
  Identifies the purpose for this name.
  Possible Values: usual, official, temp, nickname, anonymous, old, maiden
- gender
  required, string
  Administrative Gender - the gender that the patient is considered to have for administration and record keeping purposes.
  Possible Values: male, female, other, unknown
- id
  string
  The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.
- extension
  Array of race, ethnicity, birthsex, patient-citizenship or Other
  Additional information about patients not represented by standard FHIR fields.
  Any of:
  Concepts classifying the person into a named category of humans sharing common history, traits, geographical origin or nationality. The race codes used to represent these concepts are based upon the CDC Race and Ethnicity Code Set Version 1.0 which includes over 900 concepts for representing race and ethnicity of which 921 reference race. The race concepts are grouped by and pre-mapped to the 5 OMB race categories:
  
  American Indian or Alaska Native
  
  Asian
  
  Black or African American
  
  Native Hawaiian or Other Pacific Islander
  
  White.
  
  See http://hl7.org/fhir/us/core/StructureDefinition/us-core-race for more information
  url
  required, string
  Source of the definition for the extension code - a logical name or a URL.
  Value: http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
  extension
  Array of ombCategory or text
  Sub-extensions to carry more information about the patient's ethnicity
  Any of:
  The 5 race category codes according to the OMB Standards for Maintaining, Collecting, and Presenting Federal Data on Race and Ethnicity, Statistical Policy Directive No. 15, as revised, October 30, 1997.
  url
  required, string
  Source of the definition for the extension code - a logical name or a URL.
  Value: ombCategory
  valueCoding
  required, object
  Value of extension - must be one of a constrained set of the data types (see Extensibility for a list).
  system
  string
  The identification of the code system that defines the meaning of the symbol in the code.
  code
  string
  A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).
- active
  boolean
  Whether this patient record is in active use. Many systems use this property to mark as non-current patients, such as those that have not been seen for a period of time based on an organization's business rules.
  
  It is often used to filter patient lists to exclude inactive patients
  
  Deceased patients may also be marked as inactive for the same reasons, but may be active for some time after death.
- telecom
  Array of object
  A contact detail (e.g. a telephone number or an email address) by which the individual may be contacted.
  system
  required, string
  Telecommunications form for contact point - what communications system is required to make use of the contact.
  Possible Values: phone, fax, email, pager, url, sms, other
  value
  required, string
  The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
  use
  string
  Identifies the purpose for the contact point.
  Possible Values: home, work, temp, old, mobile
- birthDate
  string
  The date of birth for the individual.
- address
  Array of object
  An address for the individual.
  line
  Array of string
  This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.
  city
  string
  The name of the city, town, suburb, village or other community or delivery center.
  state
  string
  Sub-unit of a country with limited sovereignty in a federally organized country. A code may be used if codes are in common use (e.g. US 2 letter state codes).
  postalCode
  string
  A postal code designating a region defined by the postal service.
  period
  object
  Time period when address was/is in use.
  start
  string
  The start of the period. The boundary is inclusive.
  end
  string
  The end of the period. If the end of the period is missing, it means no end was known or planned at the time the instance was created. The start may be in the past, and the end date in the future, which means that period is expected/planned to end at that time.
  use
  string
  The purpose of this address.
  Possible Values: home, work, temp, old, billing
  district
  string
  The name of the administrative area (county).
  country
  string
  Country - a nation as commonly understood or generally accepted.
- contact
  Array of object
  A contact party (e.g. guardian, partner, friend) for the patient.
  relationship
  Array of object
  The nature of the relationship between the patient and the contact.
  
  Redox sends and recognizes the following values for system:
  
  http://terminology.hl7.org/CodeSystem/v3-RoleCode - used as RelationToPatient
  
  http://terminology.hl7.org/CodeSystem/v2-0131 - used as the ContactRole
  
  coding
  Array of object
  A reference to a code defined by a terminology system.
  system
  string
  The identification of the code system that defines the meaning of the symbol in the code.
  code
  string
  A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).
  text
  string
  A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the user.
  name
  object
  A name associated with the contact person.
  use
  string
  Identifies the purpose for this name.
  Possible Values: usual, official, temp, nickname, anonymous, old, maiden
  family
  string
  The part of a name that links to the genealogy. In some cultures (e.g. Eritrea) the family name of a son is the first name of his father.
  given
  Array of string
  Given name.
  telecom
  Array of object
  A contact detail for the person, e.g. a telephone number or an email address.
  system
  string
  Telecommunications form for contact point - what communications system is required to make use of the contact.
  Possible Values: phone, fax, email, pager, url, sms, other
  value
  string
  The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
  use
  string
  Identifies the purpose for the contact point.
  Possible Values: home, work, temp, old, mobile
  address
  object
  Address for the contact person.
  use
  string
  The purpose of this address.
  Possible Values: home, work, temp, old, billing
  line
  Array of string
  This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.
  city
  string
  The name of the city, town, suburb, village or other community or delivery center.
  district
  string
  The name of the administrative area (county).
  state
  string
  Sub-unit of a country with limited sovereignty in a federally organized country. A code may be used if codes are in common use (e.g. US 2 letter state codes).
  postalCode
  string
  A postal code designating a region defined by the postal service.
  country
  string
  Country - a nation as commonly understood or generally accepted.
- communication
  Array of object
  A language which may be used to communicate with the patient about his or her health.
  language
  required, object
  The ISO-639-1 alpha 2 code in lower case for the language, optionally followed by a hyphen and the ISO-3166-1 alpha 2 code for the region in upper case; e.g. "en" for English, or "en-US" for American English versus "en-EN" for England English.
  coding
  Array of object
  A reference to a code defined by a terminology system.
  system
  string
  The identification of the code system that defines the meaning of the symbol in the code.
  code
  string
  A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).
  text
  string
  A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the user.
- generalPractitioner
  Array of object
  Patient's nominated care provider.
  
  Must be a resource of type Practitioner.
  reference
  string
  A reference to another resource. This is typically either a relative reference which includes the resource type and ID, or an internal reference which starts with # and refers to a contained resource.
- managingOrganization
  object
  Organization that is the custodian of the patient record.
  
  Must be a resource of type Organization.
  reference
  string
  A reference to another resource. This is typically either a relative reference which includes the resource type and ID, or an internal reference which starts with # and refers to a contained resource.
- link
  Array of object
  Link to another patient resource that concerns the same actual patient.
  other
  required, object
  The other patient resource that the link refers to.
  
  Must be a resource of type Patient.
  reference
  string
  A reference to another resource. This is typically either a relative reference which includes the resource type and ID, or an internal reference which starts with # and refers to a contained resource.
  type
  required, string
  The type of link between this patient resource and another patient resource.
  Possible Values: replaced-by, replaces
- deceasedBoolean
  boolean
  Indicates if the individual is deceased or not.
  
  Only one of deceasedBoolean, deceasedDateTime may be present.
- deceasedDateTime
  string
  Indicates if the individual is deceased or not.
  
  Only one of deceasedBoolean, deceasedDateTime may be present.
onlyCertainMatches
boolean
Multiple results can be sent when set to false, otherwise none are sent when set to true.
count
number
Maximum number of records to return. Minimum valid value of 1.
matchScoreThreshold
number
0.0 score indicate search result does not have any attribute data in common with search input criteria; 1.0 indicates that the search result is a perfect match. If not requested, default is 0.0

Response fields and example

Example payload generated from schema

1
{
2
  "resourceType": "Bundle",
3
  "type": "searchset",
4
  "total": 1,
5
  "entry": [
6
    {
7
      "resource": {
8
        "resourceType": "Patient",
9
        "id": "RedoxPatientExampleTimothy",
10
        "meta": {
11
          "extension": [
12
            {
13
              "url": "https://fhir.redoxengine.com/StructureDefinition/example-sort-order",
14
              "valueInteger": 1
15
            }
16
          ]
17
        },
18
        "extension": [
19
          {
20
            "extension": [
21
              {
22
                "url": "text",
23
                "valueString": "White"
24
              }
25
            ],
26
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
27
          },
28
          {
29
            "extension": [
30
              {
31
                "url": "ombCategory",
32
                "valueCoding": {
33
                  "code": "2135-2",
34
                  "system": "urn:oid:2.16.840.1.113883.6.238",
35
                  "display": "Hispanic or Latino"
36
                }
37
              },
38
              {
39
                "url": "text",
40
                "valueString": "Hispanic"
41
              }
42
            ],
43
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity"
44
          }
45
        ],
46
        "identifier": [
47
          {
48
            "value": "0000000001",
49
            "system": "urn:redox:health-one:MR"
50
          },
51
          {
52
            "value": "101-01-0001",
53
            "system": "http://hl7.org/fhir/sid/us-ssn"
54
          }
55
        ],
56
        "name": [
57
          {
58
            "given": [
59
              "Timothy",
60
              "Paul"
61
            ],
62
            "family": "Bixby",
63
            "use": "official"
64
          },
65
          {
66
            "text": "Billy",
67
            "use": "usual"
68
          }
69
        ],
70
        "gender": "male",
71
        "birthDate": "2008-01-06",
72
        "telecom": [
73
          {
74
            "value": "+18088675301",
75
            "system": "phone",
76
            "use": "home"
77
          },
78
          {
79
            "value": "+18008675309",
80
            "system": "phone",
81
            "use": "work"
82
          },
83
          {
84
            "value": "timothy.bixby@redoxengine.com",
85
            "system": "email"
86
          }
87
        ],
88
        "address": [
89
          {
90
            "line": [
91
              "4762 Hickory Street"
92
            ],
93
            "city": "Monroe",
94
            "district": "Greene",
95
            "state": "WI",
96
            "postalCode": "53566",
97
            "country": "US",
98
            "use": "home"
99
          }
100
        ],
101
        "maritalStatus": {
102
          "coding": [
103
            {
104
              "code": "M",
105
              "system": "http://hl7.org/fhir/v3/MaritalStatus",
106
              "display": "Married"
107
            }
108
          ],
109
          "text": "Married"
110
        },
111
        "communication": [
112
          {
113
            "language": {
114
              "coding": [
115
                {
116
                  "code": "en",
117
                  "system": "urn:ietf:bcp:47"
118
                }
119
              ],
120
              "text": "English"
121
            }
122
          }
123
        ],
124
        "contact": [
125
          {
126
            "name": {
127
              "given": [
128
                "Barbara"
129
              ],
130
              "family": "Bixby"
131
            },
132
            "telecom": [
133
              {
134
                "value": "+18088675303",
135
                "system": "phone",
136
                "use": "home"
137
              },
138
              {
139
                "value": "barbara.bixby@redoxengine.com",
140
                "system": "email"
141
              }
142
            ],
143
            "address": {
144
              "line": [
145
                "4762 Hickory St."
146
              ],
147
              "city": "Monroe",
148
              "district": "Green",
149
              "state": "WI",
150
              "postalCode": "53566",
151
              "country": "USA"
152
            },
153
            "relationship": [
154
              {
155
                "coding": [
156
                  {
157
                    "code": "MTH",
158
                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
159
                    "display": "mother"
160
                  }
161
                ],
162
                "text": "Mother"
163
              },
164
              {
165
                "coding": [
166
                  {
167
                    "code": "C",
168
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
169
                    "display": "Emergency Contact"
170
                  }
171
                ],
172
                "text": "Emergency Contact"
173
              }
174
            ]
175
          }
176
        ],
177
        "generalPractitioner": [
178
          {
179
            "reference": "Practitioner/RedoxPractitionerExamplePat"
180
          }
181
        ],
182
        "managingOrganization": {
183
          "reference": "Organization/RedoxOrganizationManagingExample"
184
        }
185
      },
186
      "search": {
187
        "extension": [
188
          {
189
            "url": "http://hl7.org/fhir/StructureDefinition/match-grade",
190
            "valueCode": "certain"
191
          }
192
        ],
193
        "mode": "match"
194
      }
195
    }
196
  ]
197
}

resourceType
required, string
Identifies the type of the resource
Value: Bundle
type
required, string
Identifies this bundle as a response to a search
Value: searchset
total
required, number
The total number of matches
entry
required, Array of Patient, OperationOutcome or Other
A resource matching the search criteria or related to a matching resource

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.