Resource Structure

Health Gorilla FHIR APIs use standard JSON formatting for all FHIR resources, consistent with the HL7 specification. Understanding the structure of these resources helps you parse responses, identify key fields, and construct valid requests.

Resource Format

Each FHIR resource is returned as a structured JSON object with consistent top-level fields. The most common fields and their purpose are listed below.

Field	Description
`resourceType`	The FHIR resource type (for example, `Patient`, `Observation`, `DocumentReference`)
`id`	The unique identifier assigned to this resource by the system
`meta`	Metadata used for tagging, versioning, and classification
`text`	Optional human-readable summary (used primarily for CCD documents)
`extension`	Custom elements not defined in the base FHIR specification
`identifier`	One or more business identifiers for the resource, such as MRNs or external IDs

Timestamps and Time Zones

Health Gorilla returns all time values using standard FHIR dateTime and instant types. These fields follow a consistent rendering rule so your system can parse and interpret them reliably.

All timestamps:

Include an explicit time zone
Are expressed in Coordinated Universal Time (UTC)
Use the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
Apply across all environments (sandbox and production)
Apply across all FHIR resources, including meta.lastUpdated, Encounter.period, and Observation.effectiveDateTime

Example: UTC Timestamp

"meta": {
  "lastUpdated": "2025-02-12T14:23:57Z"
}

Your system should convert these UTC timestamps into the appropriate local time zone when storing, displaying, or analyzing data. Consistent UTC formatting ensures accurate interpretation across API responses, event-driven notifications (such as Subscriptions), and SFTP-based deliveries.

Identifiers

Most resources include an identifier array containing one or more business identifiers. These may be used for deduplication, patient matching, or referencing across systems.

Each identifier typically includes:

system: The namespace or coding system (such as http://hl7.org/fhir/sid/us-ssn)
value: The unique ID within that system
use: Optional indicator such as usual or official

Example: Identifier

"identifier": [
{
"system": "http://hospital.example/mrn",
"value": "123456",
"use": "official"
}
]

Metadata Fields

As identified in the table, the meta object stores system-level metadata that supports versioning, security, routing, and conformance.

Field	Description
`meta.versionId`	Version of the resource, incremented on update
`meta.lastUpdated`	Timestamp of the last modification
`meta.tag`	Routing tags used for delivery workflows and result assignment
`meta.security`	Security labels used to classify and protect sensitive resources
`meta.profile`	Canonical URLs representing conformance profiles (if applicable)

Metadata Tags

Tags support custom workflows, access control, provenance, and regulatory compliance. Use meta.tag to classify, route, and secure FHIR resources.

Typical tagging use cases include:

Data routing: Route resources to specific inboxes, services, or endpoints.
Access control: Limit visibility by user role, organization, or context.
Source attribution: Identify the submitting system to support traceability.
Security classification: Mark records as sensitive, restricted, or internal-only.
Workflow status: Track document lifecycle (for example, reviewed, signed, transmitted).

Example: Metadata Tag

"meta": {
"tag": [
{
"system": "https://healthgorilla.com/tags/routing",
"code": "p360",
"display": "Patient360 Aggregated Record"
}
]
}

system: URI representing the tag namespace
code: Machine-readable code for the tag's function or classification
display: Optional human-readable label

References and Bundles

FHIR resources use lightweight string references to establish relationships. In most cases, your system must request referenced resources individually. The following scenarios return related content together.

Reference is included using the _include search parameter
Resource is returned as part of a Bundle from a $everything or $p360-retrieve operation

Example: Reference

"subject": { "reference": "Patient/12345" }

Documents and Files

Structured and unstructured clinical documents are represented with DocumentReference and Binary.

Use the following patterns to retrieve content:

Retrieve structured clinical documents through DocumentReference
Download original files, such as PDFs or images, using the Binary resource
DocumentReference.content.attachment includes a url field that points to the downloadable file

Example: DocumentReference

{
"resourceType": "DocumentReference",
"id": "doc-67890",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "https://api.healthgorilla.com/fhir/R4/Binary/abcdef123456",
"title": "Discharge Summary - 2024-02-10"
}
}
]
}

Arrays, Nulls, and Omitted Fields

To parse responses correctly, apply the following structural rules:

Arrays such as identifier, telecom, or address may contain one or more elements depending on the source.
Unavailable fields are omitted rather than set to null.
For large result sets, follow pagination links using the link.relation = "next" pattern.

Coding and Terminologies

Use standard code systems such as LOINC, SNOMED CT, RxNorm, and ICD-10, to represent clinical concepts in a consistent, interoperable way. Encode values with a coding[] array that includes system, code, and display.

Example: Coding

"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "718-7",
"display": "Hemoglobin [Mass/volume] in Blood"
}
]
}

Common Patterns

The following patterns appear across most Health Gorilla FHIR responses:

Timestamps use ISO 8601 with the UTC time zone.
Null or unavailable fields are omitted.
Arrays may contain one or many elements.
Pagination links appear as link[].relation = "next"