Patient

Patient is a FHIR resource that contains demographic and administrative information about an individual receiving healthcare services. It serves as the central reference point for all other healthcare data.

The Patient resource captures essential demographic data including names, addresses, contact information, birth date, gender, and identifiers. It also includes administrative information such as marital status, language preferences, and managing organization references.

As the foundational resource in FHIR, Patient is referenced by virtually all other clinical and administrative resources. Every payer makes this resource available, making it one of the most fundamental building blocks Flexpa provides access to.

Patient data is structured according to several implementation guides:

US Core Patient Profile - Defines the minimum conformance requirements for Patient resources in US healthcare
CARIN for Blue Button® Patient Profile - Extends US Core with additional payer-specific requirements

This reference explains the key elements of the Patient resource and how they are used in the context of health insurance data. Data types used in this reference are defined in the FHIR R4 Data Types specification.

FHIR API

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

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

Need all patient data?

Patient $everything

Retrieve all resources associated with a patient in a single API call - including EOBs, Coverage, and clinical data

Learn about $everything →

#Schema

#All Patients

The FHIR R4 Patient resource represents an individual receiving healthcare services. As a FHIR resource, it follows standard FHIR patterns with common elements like resourceType, id, meta, and identifier.

Patient resources contain demographic and administrative information that is essential for identifying individuals and coordinating their care across healthcare systems.

The Patient FHIR Resource specification includes a comprehensive set of data elements. The elements documented below represent the core FHIR R4 Patient resource elements that are commonly used across all implementations.

Elements

metaMeta: Metadata about the resource. See also Tags defined by Flexpa.
lastUpdatedinstant: The last time the patient record was updated in the payer's system
activeboolean: Whether this patient record is in active use - typically true for all current records
namearray: Names associated with the patient
usecode: The context / formality in which this name is used; Codes
usual
Known as/conventional/the one you normally use
official
The formal name as registered in an official registry
temp
A temporary name
nickname
A name that is used to address the person informally
anonymous
Anonymous assigned name
old
This name is no longer in use
maiden
Name changed for marriage
textstring: Text representation of the full name
familystring: Family name (often called 'Surname' or 'Last Name')
givenarray: Given names (not always 'first'). Includes middle names
prefixarray: Parts that come before the name (e.g., Dr, Mr, Ms)
suffixarray: Parts that come after the name (e.g., Jr, III, MD)
periodPeriod: Time period when this name was valid for use
telecomarray: Contact details for the patient
systemcode: Telecommunications form for contact; Codes
phone
The value is a telephone number used for voice calls
fax
The value is a fax machine number
email
The value is an email address
pager
The value is a pager number
url
The value is a URL
sms
The value is a SMS capable phone number
other
Some other kind of telecommunications system
valuestring: The actual contact point details (phone number, email address, etc.)
usecode: Purpose of this contact point; Codes
home
Home environment
work
Work environment
temp
Temporary contact point
old
This contact point is no longer in use
mobile
Mobile (cellular) phone
rankpositiveInt: Preferred order of use (1 = highest)
periodPeriod: Time period when the contact point was/is in use
gendercode: Administrative gender - may be used for administrative purposes; Codes
male
Male gender
female
Female gender
other
Other gender
unknown
Unknown gender
birthDatedate: The date of birth for the patient
deceasedDateTimedateTime: Date and time of death if applicable
addressarray: Addresses for the patient
usecode: The purpose of this address; Codes
home
Home address
work
Work address
temp
Temporary address
old
This address is no longer in use
billing
An address to be used to send bills, invoices, etc.
typecode: The type of address; Codes
postal
Mailing address
physical
Physical location that can be visited
both
Both postal and physical address
textstring: Text representation of the full address
linearray: Street name, number, direction & P.O. Box etc.
citystring: Name of city, town etc.
statestring: USPS Two Letter Alphabetic Codes
postalCodestring: US Zip Codes
countrystring: Country (e.g., may be ISO 3166 2 or 3 letter code)
periodPeriod: Time period when address was/is in use
linkarray: Links to other patient or related person resources. This element is used to establish relationships between patient records, such as during record merging or when linking records across different healthcare systems. See the FHIR Patient Linking documentation for more details.
otherReference(Patient|RelatedPerson): The other patient or related person resource that the link refers to
typecode: The type of link; Codes
replaced-by
This patient record has been replaced by another patient record
replaces
This patient record replaces another patient record
refer
This patient record is linked to another patient record for reference purposes
seealso
This patient record links to another patient record that may contain overlapping information

Patient Example

{
  "resourceType": "Patient",
  "id": "f8b7c4d2-9e3a-4f5b-a1c6-2d8e7b9f5c3a",
  "meta": {
    "lastUpdated": "2023-01-01T00:00:00Z"
  },
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Doe",
      "given": ["John", "Michael"],
      "prefix": ["Mr."]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "555-123-4567",
      "use": "home"
    },
    {
      "system": "email",
      "value": "john.doe@example.com",
      "use": "home"
    }
  ],
  "gender": "male",
  "birthDate": "1985-07-15",
  "address": [
    {
      "use": "home",
      "type": "both",
      "line": ["123 Main Street", "Apt 4B"],
      "city": "Anytown",
      "state": "CA",
      "postalCode": "12345",
      "country": "USA"
    }
  ]
}

#US Core Patients

The US Core Patient Profile defines additional constraints and extensions for Patient resources used in the United States healthcare context. This profile builds upon the base FHIR Patient resource and establishes minimum requirements for interoperability.

US Core requires specific elements to be supported and adds additional constraints to ensure consistent implementation across US healthcare systems.

Elements

metaMeta: Resource metadata
profilearray: http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
extensionarray: US Core Extensions - array of extension objects identified by their URL
urluri: Identifies which extension is being used. US Core defines the following extensions:; http://hl7.org/fhir/us/core/StructureDefinition/us-core-race - Race

http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity - Ethnicity

http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex - Birth Sex
extensionarray: For us-core-race and us-core-ethnicity extensions - nested extension arrays are used
urlstring: Sub-extension type: ombCategory, detailed, or text
valueCodingCoding: When extension is us-core-race and the sub-extension is ombCategory, the value represents one of the 5 OMB race categories from Standards for Maintaining, Collecting, and Presenting Federal Data on Race and Ethnicity, Statistical Policy Directive No. 15, as revised, October 30, 1997; Systemurn:oid:2.16.840.1.113883.6.238
A limited subset of CDC Race & Ethnicity Codes (CDCREC)
Codes
1002-5
American Indian or Alaska Native
2028-9
Asian
2054-5
Black or African American
2076-8
Native Hawaiian or Other Pacific Islander
2106-3
White; Systemhttp://terminology.hl7.org/CodeSystem/v3-NullFlavor
Additional codes for cases where race information was requested but not obtained or is unknown
Codes
ASKU
Asked but unknown
UNK
Unknown
valueCodingCoding: When extension is us-core-race and the sub-extension is detailed, all available codes from CDC Race & Ethnicity Codes (CDCREC) are used; Systemurn:oid:2.16.840.1.113883.6.238
The full set of CDCREC codes
Example Codes
2113-9
Irish
valueCodingCoding: When extension is us-core-ethnicity and the sub-extension is ombCategory, the value represents one of the 2 OMB ethnicity categories from Standards for Maintaining, Collecting, and Presenting Federal Data on Race and Ethnicity, Statistical Policy Directive No. 15, as revised, October 30, 1997; Systemurn:oid:2.16.840.1.113883.6.238
A two code subset of CDC Race & Ethnicity Codes (CDCREC)
Codes
2135-2
Hispanic or Latino
2186-5
Not Hispanic or Latino; Systemhttp://terminology.hl7.org/CodeSystem/v3-NullFlavor
Additional codes for cases where ethnicity information was requested but not obtained or is unknown
Codes
ASKU
Asked but unknown
UNK
Unknown
valueCodingCoding: When extension is us-core-ethnicity and the sub-extension is detailed, a subset of 41 codes from CDC Race & Ethnicity Codes (CDCREC) are used that are grouped into the 2 OMB ethnicity categories; Systemurn:oid:2.16.840.1.113883.6.238
A 41 code subset of CDC Race & Ethnicity Codes (CDCREC) for detailed ethnicity
Example Codes
2148-5
Mexican; Systemhttp://terminology.hl7.org/CodeSystem/v3-NullFlavor
Additional codes for cases where detailed ethnicity information was requested but not obtained, is unknown, or is other than the defined values
Codes
ASKU
Asked but unknown
OTH
Other
UNK
Unknown
valueStringstring: For text sub-extension for either the us-core-race or us-core-ethnicity extensions, this is free text that may have been reported by patient
valueCodecode: When extension is us-core-birthsex, the value represents birth sex assigned at birth; Systemhttp://terminology.hl7.org/CodeSystem/v3-AdministrativeGender
Birth sex codes from HL7 v3 Administrative Gender
Codes
F
Female
M
Male; Systemhttp://terminology.hl7.org/CodeSystem/v3-NullFlavor
Additional codes for cases where birth sex information was requested but not obtained, is unknown, or is other than male/female
Codes
ASKU
Asked but unknown
OTH
Other
UNK
Unknown
communicationBackboneElement: Language communication abilities
languageCodeableConcept: The language for communication; Systemurn:ietf:bcp:47
IETF language tag
Example Codes
en
English
es
Spanish
preferredboolean: Language preference indicator

US Core Patient Example

{
  "resourceType": "Patient",
  "id": "c7e5a4b9-3f2d-4e1a-8b6c-9d8e7f5c2a1b",
  "meta": {
    "lastUpdated": "2023-10-15T14:30:00Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    ]
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2106-3",
            "display": "White"
          }
        },
        {
          "url": "detailed",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2113-9",
            "display": "Irish"
          }
        },
        {
          "url": "text",
          "valueString": "White - Irish"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2186-5",
            "display": "Not Hispanic or Latino"
          }
        },
        {
          "url": "text",
          "valueString": "Not Hispanic or Latino"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
      "valueCode": "F"
    }
  ],
  "name": [
    {
      "family": "O'Sullivan",
      "given": ["Siobhan", "Mary"]
    }
  ],
  "gender": "female",
  "birthDate": "1985-08-23",
  "address": [
    {
      "line": ["742 Evergreen Terrace"],
      "city": "San Diego",
      "state": "CA",
      "postalCode": "92101"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "619-555-7890",
      "use": "mobile"
    },
    {
      "system": "email",
      "value": "siobhan.osullivan@example.com"
    }
  ],
  "communication": [
    {
      "language": {
        "coding": [
          {
            "system": "urn:ietf:bcp:47",
            "code": "en",
            "display": "English"
          }
        ]
      },
      "preferred": true
    }
  ]
}

#CARIN Blue Button Patients

The CARIN Consumer Directed Payer Data Exchange (CARIN IG) for Blue Button® Patient Profile extends the US Core Patient Profile with additional requirements specific to payer data exchange scenarios.

This profile is designed to support consumer-directed exchange of health insurance information and ensures that payer systems can provide consistent patient demographic data to members.

Elements

metaMeta: Resource metadata
profilearray: http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient
identifierarray: Business and administrative identifiers for the Patient
typeCodeableConcept: Must include member identifier type (MB); Systemhttp://terminology.hl7.org/CodeSystem/v2-0203
HL7-defined code system of concepts specifying type of identifier used in HL7 Version 2.x
Codes
MB
The Member Id is the identifier payers assign to a beneficiary for a contract; it may be different for various lines of business; ie. QHP vs MA
MR
An identifier that is unique to a patient within a set of medical records, not necessarily unique within an application
MA
Medicaid number - an optional identifier
MC
Medicare number - an optional identifier; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType
Identifier Type codes that extend those defined in HL7 Version 2.x to define the type of identifier payers and providers assign to claims and patients
Codes
um
A unique member identifier assigned by a payer across all lines of business
pat
Patient Account Number

CARIN Patient Example

{
  "resourceType": "Patient",
  "id": "c7e5a4b9-3f2d-4e1a-8b6c-9d8e7f5c2a1b",
  "meta": {
    "lastUpdated": "2023-10-15T14:30:00Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient"
    ]
  },
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MB",
            "display": "Member Number"
          }
        ]
      },
      "system": "https://example-payer.com/member-ids",
      "value": "987654321"
    },
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "um",
            "display": "Unique Member ID"
          }
        ]
      },
      "system": "https://example-payer.com/unique-member-ids",
      "value": "UM-987654321"
    }
  ],
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2106-3",
            "display": "White"
          }
        },
        {
          "url": "detailed",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2113-9",
            "display": "Irish"
          }
        },
        {
          "url": "text",
          "valueString": "White - Irish"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2186-5",
            "display": "Not Hispanic or Latino"
          }
        },
        {
          "url": "text",
          "valueString": "Not Hispanic or Latino"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
      "valueCode": "F"
    }
  ],
  "name": [
    {
      "family": "O'Sullivan",
      "given": ["Siobhan", "Mary"]
    }
  ],
  "gender": "female",
  "birthDate": "1985-08-23",
  "address": [
    {
      "line": ["742 Evergreen Terrace"],
      "city": "San Diego",
      "state": "CA",
      "postalCode": "92101"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "619-555-7890",
      "use": "mobile"
    },
    {
      "system": "email",
      "value": "siobhan.osullivan@example.com"
    }
  ],
  "communication": [
    {
      "language": {
        "coding": [
          {
            "system": "urn:ietf:bcp:47",
            "code": "en",
            "display": "English"
          }
        ]
      },
      "preferred": true
    }
  ]
}

#API

GEThttps://api.flexpa.com/fhir/Patient/:id

#Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

When using the read operation with Patient resources, you can use the $PATIENT_ID wildcard which will automatically be replaced with the authenticated patient's ID.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token

Request path parameters

idstring: The identifier of the resource to be retrieved - use $PATIENT_ID to automatically reference the authenticated patient

Request

GET

/fhir/Patient/:id

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Patient/$PATIENT_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Patient",
  "id": "a85f4c92-1b6d-4e3a-9c2f-8d7e5b3f2a1c",
  "meta": {
    "lastUpdated": "2023-01-01T00:00:00Z"
  },
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": ["John"]
    }
  ],
  "gender": "male",
  "birthDate": "1980-01-01"
}

GEThttps://api.flexpa.com/fhir/Patient

#Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token

Search parameters

identifiertoken: A patient identifier
namestring: A server defined search that may match any of the string fields in HumanName
givenstring: A portion of the given name of the patient
familystring: A portion of the family name of the patient
gendertoken: Gender of the patient
birthdatedate: The patient's date of birth
telecomtoken: The value in any kind of telecom details of the patient
emailtoken: A value in an email contact
phonetoken: A value in a phone contact
organizationreference: The organization that is the custodian of the patient record
activetoken: Whether the patient record is active
languagetoken: Language code (from Patient.communication.language)
linkreference: All patients linked to the given patient

Request

GET

/fhir/Patient

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Patient \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "a85f4c92-1b6d-4e3a-9c2f-8d7e5b3f2a1c",
        "meta": {
          "lastUpdated": "2023-01-01T00:00:00Z"
        },
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Smith",
            "given": ["John"]
          }
        ],
        "gender": "male",
        "birthDate": "1980-01-01"
      }
    }
  ]
}

GEThttps://api.flexpa.com/fhir/Patient/:id/$everything

#$everything

Unique to the Patient resource, the Patient $everything Operation returns all patient-compartmentalized resources, as well as any Organization, Location, Practitioner, and Medication resources that are present in the patient's FHIR data.

This request returns large Bundles. The client should be prepared to handle a potentially large single response.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token

Request path parameters

idstring: The identifier of the patient - use $PATIENT_ID to automatically reference the authenticated patient

Response fields

ResponseBundle: Patient $everything returns a Bundle that contains all resources that reference the Patient resource.

Request

GET

/fhir/Patient/:id/$everything

ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$everything' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Bundle",
  "entry": [
    { "resource": {"resourceType": "Patient", ...} },
    { "resource": {"resourceType": "Coverage", ...} },
    { "resource": {"resourceType": "ExplanationOfBenefit", ...} },
  ]
}

POSThttps://api.flexpa.com/fhir/Patient/:id/$expunge

#$expunge

The $expunge operation deletes all resources in a specific Patient resource compartment. This operation performs a "hard" delete, meaning all data, including resource history, is permanently removed from the server.

Once the data is deleted, any subsequent FHIR requests to retrieve the data will return a 404 status code.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token

Request path parameters

idstring: The identifier of the patient whose data you want to delete - use $PATIENT_ID to automatically reference the authenticated patient

Response fields

ResponseOperationOutcome: The Patient $expunge operation returns an OperationOutcome resource, indicating the success or failure of the expunge request.

Request

POST

/fhir/Patient/:id/$expunge

ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$expunge' \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -X POST

Response

{
  "resourceType": "OperationOutcome",
  "id": "accepted",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "text": "Accepted"
      },
      "diagnostics": "http://medplum.flexpa.com/fhir/R4/job/15c72fcc-267e-4372-a85e-26fa20b01634/status"
    }
  ],
  "extension": [
    {
      "url": "https://medplum.com/fhir/StructureDefinition/tracing",
      "extension": [
        {
          "url": "requestId",
          "valueUuid": "175885a0-d396-4d1d-9c9d-a618f06cfdc8"
        },
        {
          "url": "traceId",
          "valueUuid": "5e18c528-a74a-4dac-9cec-b35a2ce33c3e"
        }
      ]
    }
  ]
}

POSThttps://api.flexpa.com/fhir/Patient/:id/$health-cards-issue

#$health-cards-issue

The $health-cards-issue operation creates a SMART Health Card containing the patient's health data as a verifiable credential. This operation generates a digitally signed JWT that packages the patient's FHIR data according to the SMART Health Cards specification.

The operation always uses the patient's complete data set (equivalent to Patient/$everything), ensuring comprehensive health information is included in the credential.

The health card is returned as a signed JWT string within a Parameters resource, not as a raw SMART Health Card file. The JWT can be converted to a QR code or shared directly as a verifiable credential.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token

Request path parameters

idstring: The identifier of the patient - use $PATIENT_ID to automatically reference the authenticated patient

Request body

resourceTypestring: Must be Parameters
parameterarray: Array containing exactly one parameter object
namestring: Must be credentialType
valueUristring: Must be Patient/$everything (currently the only supported credential type)

Response fields

ResponseParameters: Returns FHIR Parameters resource containing the SMART Health Card
parameterarray: Array containing exactly one parameter object
namestring: Will be verifiableCredential
valueStringstring: The signed SMART Health Card as a JWT string

Request

POST

/fhir/Patient/:id/$health-cards-issue

ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$health-cards-issue' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {
        "name": "credentialType",
        "valueUri": "Patient/$everything"
      }
    ]
  }'

Request Body

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "credentialType",
      "valueUri": "Patient/$everything"
    }
  ]
}

Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "verifiableCredential",  
      "valueString": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjNLZmRnLVh3UC03Z..."
    }
  ]
}