The FHIR STU3 Patient resource defines demographics, care providers, and other administrative information about a person receiving care at a health organization. The Patient resource can be thought of as the starting point for many different client application workflows; often, a workflow will begin with a patient query and selection, and the server ID will be used to drive additional queries for diagnostic and care-related information.

FHIR Resource: Patient <https://www.hl7.org/fhir/patient.html>

https://api.healthgorilla.com/fhir/Patient

Supported Attributes

Field Name	Comments
active
identifier	MRN SSN External Identifier (Can be a custom system declared by the user).
photo
name	Support for family(required), given(required), suffix (optional). Example "name": [ { "use": "usual", "family": "Doe", "given": [ "John" ], "suffix": [ "Sr." ] } ],
gender
birthDate
deceased
telecom
address
maritalStatus
communication
managingOrganization
link
http://hl7.org/fhir/extension-patient-interpreterrequired.html	Interpreter Required
http://hl7.org/fhir/us/core/StructureDefinition-us-core-race.html	Race
http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity	Ethnicity

📘
API Reference - Patient
Check out the FHIR RESTful Patient API in the Sandbox environment.

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/Patient/`{ID}`	GET	Retrieve patient by ID

2. Search

HTTP Request	Method	Action
/Patient?[parameter=`{value}`]	GET	Retrieve Patient resources meeting the specified search criteria

Search Parameters:

Name	Type	Description
identifier	Token	Patient Identifier (MRN)
family	String	Patient Family Name
given	String	Patient Given Name
birthdate	String	Patient DOB (in YYYY-MM-DD format)
gender	Token	Patient Gender (F/M)
address-postalcode	String	Patient Postal (zip) code
_lastUpdated	Date
_offset	Number
_count	Number

Examples

2.1. Search patients updated since March 2019

https://api.healthgorilla.com/fhir/Patient?
_lastUpdated=gt2019-03&
_offset=0&_count=5

2.2. Search patient by HG Global ID

https://api.healthgorilla.com/fhir/Patient?
identifier=https://www.healthgorilla.com|8063965523692105bfc35def

2.3 Search patient by External MRN

https://api.healthgorilla.com/fhir/Patient?
identifier=<CUSTOM CODE SYSTEM>|A3dr234112

https://api.healthgorilla.com/fhir/Patient?
identifier=http://terminology.hl7.org/CodeSystem/v2-0203|A3dr234112

2.4 Search patient by Custom Code System (External ID)

https://api.healthgorilla.com/fhir/Patient?
identifier=<CUSTOM CODE SYSTEM>|A3dr234112

2.5 Search patient by SSN

https://api.healthgorilla.com/fhir/Patient?
identifier=http://hl7.org/fhir/sid/us-ssn|000-00-0001

2.6 Search patient by name

https://api.healthgorilla.com/fhir/Patient?
given=Homer&family=Simpson

2.7 Search all male patients who were born after October 1998 and whose given name contains ‘Alex’

https://api.healthgorilla.com/fhir/Patient?
given:contains=Alex
&birthdate=gt1998-10
&gender=male

2.8 Search patients with the exact string ‘Smith Johnson’. Exact searching is case sensitive

https://api.healthgorilla.com/fhir/Patient?
family:exact=Smith%20Johnson

2.9 Search patients by name with a suffix (where last name is 'Gorilla, Jr.')

https://api.healthgorilla.com/fhir/Patient?given=Joe&family=Gorilla%5C%2C%20Jr.

3. Create

HTTP Request	Method	Action
/Patient	POST	Creates patient resource

The following attributes are required:

Name	Details
name
gender
birthDate

Examples

3.1 Add an external MRN for the patient

An external MRN can be associated with the patient. This MRN can be used to retrieve the patient FHIR resource as in example 2.3. The external MRN is also visible within the patient chart in the Health Gorilla UI and is sent to external laboratories when orders are placed from within Health Gorilla. The MRN is placed inside of the identifier attribute for the patient along with a customer code system. This code system can be your own company's URL for example.

"identifier": [
        {
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "MR",
                        "display": "Medical record number"
                    }
                ],
                "text": "Medical record number"
            },
          	"system": "{{CUSTOM CODE SYSTEM}}",
            "value": "{{mrn}}"
        }
    ],

3.2 Add an external identifier for the patient

Additional identifiers can be associated with a patient. Identifiers require the following attributes:

"system"
"value"
These identifiers can be used in retrieving a Patient resource as described in section 2.4. They are not visible in the patient chart inside the Health Gorilla User Interface.

"identifier": [
          {
            "system": "<SYSTEM_NAME>",
            "value": "<EXTERNAL IDENTIFIER>"
          }
        ],

3.3. Conditional create

This method also supports conditional create. To use it, you need to set additional header:
If-None-Exist: [search parameters]

Supported parameters:

given
family
gender
birthdate

If-None-Exist: given=Rajesh&family=Koothrappali&gender=male&birthdate=1981-01-30

3.4 Override Duplication Throttle

🚧
Health Gorilla limits duplicate patients to 10 before returning an error. Duplicates are determined by the patient demographics that are received in the request. The exception is when the request payload contains an external MRN. This field must always be unique within the the tenant.

This header will allow a user to create more than 10 duplicates of the same patient. This is not recommended, but could happen if duplicate records for a patient exist in the customer's system. To use this functionality, set an addition request header: Prefer:create-always

GET /fhir/Patient/
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
Prefer: create-always

4. Update

Name	Method	Action
/Patient/`{ID}`	PUT	Updates patient resource

Update operation supports ‘Optimistic Locking’
See <https://www.hl7.org/fhir/http.html#concurrency> for more details.

If passed resource does not exist then it will be created (HTTP 201).

5. Export C-CDA

You can export patient's full medical history as a single C-CDA document.

HTTP Request	Method	Action
/Patient/`{ID}`/$export-ccda	GET	Generate C-CDA CCD document.

You can specify the client timezone by passing it in the ‘tz’ attribute.

The result contains a link to a binary resource (CCD XML) that can be downloaded.

🚧
This operations can take a long time to complete, therefore it must be performed asynchronously.

Example

https://api.healthgorilla.com/fhir/Patient/03db4352ee0190ad5e9e6748/$export-ccda?tz=America/Los_Angeles&_format=json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "url",
            "valueString": "https://api.healthgorilla.com/fhir/Binary/tmp-4dc6cb5db2c07903552a5dcc"
        },
        {
            "name": "contentType",
            "valueString": "text/xml"
        },
        {
            "name": "format",
            "valueCoding": {
                "system": "urn:oid:1.3.6.1.4.1.19376.1.2.3",
                "code": "urn:ihe:pcc:xphr:2007",
                "display": "HL7 CCD Document"
            }
        },
        {
            "name": "size",
            "valuePositiveInt": 1258668
        },
        {
            "name": "checksum",
            "valueString": "274dc07eedb00fadcbb9876958e65d67"
        },
        {
            "name": "expiredAt",
            "valueDateTime": "2019-11-13T12:31:01+03:00"
        }
    ]
}

6. Return all the information related to one patient

Health Gorilla implements FHIR $everything operation that can be used to retrieve all the information related to a given patient.

Name	Method	Action
/Patient/`{ID}`/$everything	GET	Read all records related to the specified patient.

Supported parameters:

Name	Type	Description
start	date	The date range relates to care dates. Return all records relating to care provided in a certain date range
end	date	The date range relates to care dates. Return all records relating to care provided in a certain date range.
_since	datetime	Resources updated after this period will be included in the response.
_type	code	One or more parameters, each containing one or more comma-delimited FHIR resource types to include in the return resources.

Examples

6.1. Return all DiagnosticReports, Observations, Immunizations, Encounters updated since 2019-09-01

https://api.healthgorilla.com/fhir/Patient/03db4352ee0190ad5e9e6748/$everything
?_format=json
&_type=DiagnosticReport,Observation,Immunization,Encounter
&_since=2019-09-01

6.2. Return all information for the specified patient

https://api.healthgorilla.com/fhir/Patient/03db4352ee0190ad5e9e6748/$everything

7. Merge

Health Gorilla provides an API for merging two patient records into one. This can be used if duplicate patient records are found to have been created in your tenant.

❗️
Warning
Note that any parameters of the source patient that differ from the target will be lost.

Endpoint	HTTP Method
/Patient/$merge	POST

Payload

When constructing the merge request payload, either logical or literal references to the source and target patients can be used.

Parameter	Type	Description
source-patient	valueReference	Reference to the source patient (Literal Reference)
source-patient-identifier	valueIdentifier	Source Patient Identifier (Logical Reference)
target-patient	valueReference	Reference to the target patient (LIteral Reference)
target-patient-identifier	valueIdentifier	Target Patient Identifier (Logical Reference)
preview	valueBoolean	If `True`or skipped, then do not merge the patients. Only differences in demographics will be returned. Must be set to `False` if the merge is to be executed.

{
   "name":"source-patient",
    "valueReference":{
         "reference": "Patient/Patient_HG_ID"
    }
}

{
   "name":"source-patient-identifier",
   "valueIdentifier":{
      "system":"https://www.healthgorilla.com",
      "value":"MEDICAL_RECORD_NUMBER"
   }
}

Response

The server returns HTTP 200 response FHIR Parameters payload that contains either the difference between patients or the result of the merge.

Preview Mode

You can use the preview mode to compare source and target patients without merging.
The server returns source parameters that do not match the target and will be lost after the merge.

{
            "name": "name[0].given",
            "part": [
                {
                    "name": "targetValue",
                    "valueString": "Tom"
                },
                {
                    "name": "sourceValue",
                    "valueString": "Tomas"
                }
            ]
 }

In the example above, the original patient is named "Tom". And the target patient is named "Thomas". After the merge, the original name will be replaced by the target value

Conflict Resolution

If you do want to preserve any parameters of the source patient, you need to change the target patient before merge. Use the PatientAPI and the updatemethod.

Examples

Preview Mode

{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"source-patient",
         "valueReference":{
            "reference": "Patient/6f79546225416108b9997194"
          }
      },
      {
         "name":"target-patient",
         "valueReference":{
            "reference": "Patient/60fe7f6005d26bad09670bcb"
          }
      },
      {
         "name":"preview",
         "valueBoolean":"true"
      }
   ]
}

{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"name[0].given",
         "part":[
            {
               "name":"targetValue",
               "valueString":"Tom"
            },
            {
               "name":"sourceValue",
               "valueString":"Tomas"
            }
         ]
      },
      {
         "name":"birthDate",
         "part":[
            {
               "name":"targetValue",
               "valueDate":"2002-01-02"
            },
            {
               "name":"sourceValue",
               "valueDate":"2001-01-02"
            }
         ]
      },
      {
         "name":"telecom[0].value",
         "part":[
            {
               "name":"targetValue",
               "valueString":"415 222-2222"
            },
            {
               "name":"sourceValue",
               "valueString":"415 111-1111"
            }
         ]
      }
   ]
}

Merge Mode

{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"source-patient",
         "valueReference":{
            "reference": "Patient/6f79546225416108b9997194"
          }
      },
      {
         "name":"target-patient",
         "valueReference":{
            "reference": "Patient/60fe7f6005d26bad09670bcb"
          }
      },
      {
         "name":"preview",
         "valueBoolean":"false"
      }
   ]
}

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "info",
            "valueString": "merged"
        }
    ]
}