Skip to content

Patient

Overview

Demographics and other administrative information about an individual receiving care or other health-related services. This information is used to categorize individuals for identification, records matching, and other purposes.

Each Patient has next elements:

  • a patient identifier (e.g. MRN)
  • a patient name
  • a gender*

Each Patient supports next elements:

  • contact detail (e.g. a telephone number or an email address)
  • a birth date
  • an address
  • a communication language
  • a race
  • an ethnicity
  • a birth sex*

Profile specific implementation guidance:

  • Note that Previous Name and Suffix are listed in the U.S. Core Data for Interoperability.
    • Suffix is represented using the Patient.name.suffix element.
    • Previous name is represented by providing an end date in the Patient.name.period element for a previous name.
    • The patient example below demonstrates the usage of both of these elements.
  • *The FHIR Specification provides guidance and background for representing patient gender. The American Clinical Laboratory Association (ACLA) has published best practice guidelines for administrative and clinical gender related to laboratory testing and reporting which implementers may find helpful as well.

This resource conforms to USCDI V1 profile for Patient - refer to US Core Patient Profile. Patient response will be provided in JSON (refers to Capability Statement) format as per FHIR standard R4 version.

USCore Data Element FHIR Resource Field
First Name/Middle Name Patient.name.given
Last Name Patient.name.family
Previous Name Patient.name
Suffix Patient.name.suffix
Birth Sex US Core Birth Sex Extension
Date of Birth Patient.birthDate
Race US Core Race Extension
Ethnicity US Core Ethnicity Extension
Preferred Language Patient.communication
Address Patient.address
Phone Number Patient.telecom

Must support elements, mandatory and optional search parameters

Patient must support these elements:

  • us-core-race
  • us-core-ethnicity
  • us-core-birthsex
  • identifier
    • system
    • value
  • name
    • family
    • given
  • telecom
    • system
    • value
    • use
  • gender
  • birthDate
  • address
    • line
    • city
    • state
    • postalCode
    • period
  • communication
    • language

The following search parameters and search parameter combinations SHALL be supported:

The syntax used to describe the interactions is described here.

SHALL support searching for all Patients for a patient using _id search parameter:

GET [base url]/Patient/{id}

SHALL support searching patient by an identifier such as a MPI using the identifier search parameter:

GET [base url]/Patient?identifier={system|}[code]

SHALL support searching patient by a server defined search that matches any of the string fields in the HumanName, including family, give, prefix, suffix, suffix, and/or text using the name search parameter:

GET [base url]/Patient?name=[string]

SHALL support searching using the combination of the birthdate and name search parameters:

GET [base url]/Patient?birthdate={date}&name=[string]

SHALL support searching using the combination of the gender and name search parameters:

GET [base url]/Patient?gender={system|}[code]&name=[string]

The following search parameter combinations SHOULD be supported (optional):

SHOULD support searching using the combination of the birthdate and family search parameters:

GET [base url]/Patient?birthdate={date}&family=[string]

SHOULD support searching using the combination of the family and gender search parameters:

GET [base url]/Patient?family=[string]&gender={system|}[code]

The response to any search operation is always a list of resources in a Bundle or an Operation Outcome.

Patient By Id

Get Patient by ID.

METHOD GET

[base url]/Patient/{id}

or

[base url]/Patient?_id={id}

PARAMS

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient/c5137fa5-3216-b12a-cbbc-a0c6bef361g7' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'

Patient by an identifier

Get Patients using patient by an identifier such as a MPI using the identifier search parameter

METHOD GET

GET [base url]/Patient?identifier={system|}[code]`

PARAMS

  • [base url] - FHIR base url
  • {system|} - The namespace for the identifier value
  • {code} - patient unique identifier value

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?identifier=http://hospital.smarthealthit.org|1032702' \
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by HumanName

Get Patients using matches any of the string fields in the HumanName, including family, give, prefix, suffix, suffix, and/or text using the name search parameter:

METHOD GET

GET [base url]/Patient?name=[string]

PARAMS

  • [base url] - FHIR base url
  • [string] - family or given name of the patient

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?patient=Patient/fe1cd986-1ac7-4c26-b8b3-d632a48408fd&target-date=ge2015-01-14&target-date=le2019-01-14 \
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by birthdate and name search parameters

Get Patients using the combination of the birthdate and name search parameters

METHOD GET

GET [base url]/Patient?birthdate={date}&name=[string]`

PARAMS

  • [base url] - FHIR base url
  • {Type/} - Type for the Reference. Example: Patient
  • [string] - family or given name of the patient
  • {date} - birthdate of the patient

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?birthdate={date}&name=[string] \
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by gender and name search parameters

Get Patients using the combination of gender and name search parameters

METHOD GET

GET [base url]/Patient?gender={system|}[code]&name=[string]`

PARAMS

  • [base url] - FHIR base url
  • {system|} - The namespace for the identifier value
  • {code} - patient unique identifier value
  • [string] - family or given name of the patient

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?name=Shaw&gender=female\
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by gender and name search parameters

Get Patients using the combination of gender and name search parameters

METHOD GET

GET [base url]/Patient?gender={system|}[code]&name=[string]`

PARAMS

  • [base url] - FHIR base url
  • {system|} - terminology system used to identify patient's gender
  • {code} - patient's gender
  • [string] - family or given name of the patient

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?name=Shaw&gender=female\
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by birthdate and family search parameters

Get Patients using the combination of birthdate and family search parameters

METHOD GET

GET [base url]/Patient?birthdate={date}&family=[string]

PARAMS

  • [base url] - FHIR base url
  • {date} - patient's birthdate
  • [string] - patient's family name

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?family=Shaw&birthdate=2007-03-20\
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'

Patient by birthdate and family and gender search parameters

Get Patients using the combination of family and gender search parameters

METHOD GET

GET [base url]/Patient?family=[string]&gender={system|}[code]

PARAMS

  • [base url] - FHIR base url
  • [string] - patient's family name
  • {system|} - terminology system used to identify patient's gender
  • {code} - patient's gender

HEADERS

The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.

Header Type Required/Optional Value
Authorization string required 'Bearer'

RESPONSES

Code Description Comment
200 OK The request was processed successfully
400 Bad request Invalid request parameters or FHIR operation outcome resource returned
401 Unauthorized This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource
404 no Route matched with those values The request was able to communicate with a given server, but the server could not find what was requested
500 Internal Server Error The server has encountered a situation it doesn't know how to handle

EXAMPLE:

curl --location --request GET 'https://demo.kodjin.com/fhir/Patient?family=Shaw&gender=female\
--header 'Authorization: Bearer 1239b275-909e-4754-8f73-1e411fd6769e'