Searching APIs using patient.identifier Parameter

A lot of the patient-centric FHIR APIs, such as AllergyIntolerance, Procedures and DiagnosticReport, support search using patient.identifier as a parameter. This parameter is used to resolve the patient and check the privacy settings for the patient before returning the requested resources. All successful API searches using patient.identifier parameter the will return a 200 OK response code. However, the responses may vary based on the specific scenario. The scenarios that return the same successful response code with different response details are:

Patient Resolved and One or More Resources Matched

When the patient is resolved and one or more resources are found for the resolved patient, a 200 OK response containing a list of entries will be returned. The response will look like:


{
   "resourceType":"Bundle",
   "id":"05ba45fa-d66e-4f7e-a253-5f848469230a",
   "type":"searchset",
   "total":0,
   "link":[
      {
         "relation":"self",
         "url":"/fhir/1.0/AllergyIntolerance?patient.identifier=ExampleNamespace%7C1234"
      }
   ],
   "entry":[
      {
            "fullUrl": "/fhir/1.0/AllergyIntolerance/shaNHOAPTPRM6TFSF7HGWQGGZB76HY4KJUN2SVIROVPCNZUKRTCZEOQ",
            "resource": {
                "resourceType": "AllergyIntolerance",
                "id": "shaNHOAPTPRM6TFSF7HGWQGGZB76HY4KJUN2SVIROVPCNZUKRTCZEOQ",
                "meta": {
                    "versionId": "0",
                    "lastUpdated": "2016-09-10T16:18:40.000+00:00"
                },
                "extension": [
                    {
                        "url": "http://fhir.hl7.org.nz/dstu2/StructureDefinition/agent",
                        "extension": [
                            {
                                "url": "role",
                                "valueCoding": {
                                    "system": "http://hl7.org/fhir/provenance-participant-role",
                                    "code": "custodian",
                                    "display": "Custodian"
                                }
                            },
                            {
                                "url": "actorId",
                                "valueIdentifier": {
                                    "value": "SYS_A"
                                }
                            }
                        ]
                    },
                    {
                        "url": "http://fhir.hl7.org.nz/dstu2/StructureDefinition/allergyintolerance-severity",
                        "valueCode": "invalid"
                    }
                ],
                "identifier": [
                    {
                        "system": "urn:oid:2.16.840.1.113883.3.89.900.500.10.3.2",
                        "value": "100"
                    }
                ],
                "onset": "2012-01-15",
                "patient": {
                    "reference": "Patient/IFAUCQJNGAYTENBNHBAE6USJJ5HA"
                },
                "substance": {
                    "coding": [
                        {
                            "system": "http://www.system-a.example/snm",
                            "code": "387458008",
                            "display": "Aspirin"
                        }
                    ],
                    "text": "Aspirin"
                },
                "status": "active",
                "category": "medication",
                "reaction": [
                    {
                        "manifestation": [
                            {
                                "text": "Red eyes"
                            }
                        ],
                        "_severity": {
                            "extension": [
                                {
                                    "url": "http://fhir.hl7.org.nz/dstu2/StructureDefinition/originalValue",
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://www.orionhealth.com/example/severity",
                                                "code": "S"
                                            }
                                        ]
                                    }
                                },
                                {
                                    "url": "http://hl7.org/fhir/data-absent-reason",
                                    "valueCode": "unknown"
                                }
                            ]
                        }
                    },
                    {
                        "manifestation": [
                            {
                                "text": "Swelling of the lips"
                            }
                        ],
                        "_severity": {
                            "extension": [
                                {
                                    "url": "http://fhir.hl7.org.nz/dstu2/StructureDefinition/originalValue",
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://www.orionhealth.com/example/severity",
                                                "code": "S"
                                            }
                                        ]
                                    }
                                },
                                {
                                    "url": "http://hl7.org/fhir/data-absent-reason",
                                    "valueCode": "unknown"
                                }
                            ]
                        }
                    }
                ]
            }
        }
        ...
   ]
} 

Patient Resolved and No Resources Matched

When the patient is resolved and no resources are found for the resolved patient, a 200 OK response containing 0 results will be returned. The response will look like:

{
    "resourceType": "Bundle",
    "id": "05ba45fa-d66e-4f7e-a253-5f848469230a",
    "type": "searchset",
    "total": 0,
    "link": [
        {
            "relation": "self",
            "url": "/fhir/1.0/AllergyIntolerance?patient.identifier=ExampleNamespace%7C1234"
        }
    ]
} 

Patient Does Not Exist

When performing a search, there is a possibility that the patient will not be resolved. This may happen when:

  • The API consumer has no access (patient privacy) to the patient
  • The patient does not exist in the system

When this happens, the server will respond with an OperationOutcome that allows the consumer to differentiate between the case of "no data found" and "patient not found".

NOTE: This behavior does not apply when:

  • Calling the FHIR Patient API. When performing a search in FHIR Patient API for a patient that does not exist or has no access (patient privacy), an empty list is returned.
  • Calling a FHIR API using the subject.identifier parameter

The response will look like:

{
   "resourceType":"Bundle",
   "id":"05ba45fa-d66e-4f7e-a253-5f848469230a",
   "type":"searchset",
   "total":0,
   "link":[
      {
         "relation":"self",
         "url":"/fhir/1.0/AllergyIntolerance?patient.identifier=ExampleNamespace%7C1234"
      }
   ],
   "entry":[
      {
         "resource":{
            "resourceType":"OperationOutcome",
            "issue":[
               {
                  "severity":"warning",
                  "code":"not-found",
                  "details":{
                     "coding":[
                        {
                           "system":"http://hl7.org/fhir/operation-outcome",
                           "code":"MSG_NO_MATCH",
                           "display":"No Resource found matching the query \"/fhir/1.0/AllergyIntolerance?patient.identifier=ExampleNamespace%7C1234\""
                        }
                     ],
                     "text":"Patient not found"
                  }
               }
            ]
         },
         "search":{
            "mode":"outcome"
         }
      }
   ]
}