Coverage and identity data via FHIR R4 Coverage resources plus the OAuth 2.0 identity / IAS token flow used to authorize person-level queries.
openapi: 3.0.1
info:
title: Health Gorilla FHIR R4 API
description: >-
HL7 FHIR R4 REST API for the Health Gorilla health-data interoperability
network. Provides access to patient records, person-authorized federated
record retrieval across national exchange networks (QHIN / TEFCA),
diagnostic (lab and radiology) ordering and results, clinical documents,
and coverage/eligibility data. All requests require OAuth 2.0 bearer
authentication.
termsOfService: https://www.healthgorilla.com/terms-of-service
contact:
name: Health Gorilla Developer Support
email: info@healthgorilla.com
url: https://developer.healthgorilla.com
version: 'R4'
servers:
- url: https://api.healthgorilla.com/fhir/R4
description: Production
- url: https://sandbox.healthgorilla.com/fhir/R4
description: Sandbox
security:
- bearerAuth: []
tags:
- name: CapabilityStatement
description: FHIR server capability discovery.
- name: Patient
description: Patient demographics and patient-scoped record retrieval.
- name: ServiceRequest
description: Diagnostic (lab and radiology) order requests.
- name: RequestGroup
description: Parent diagnostic orders nesting individual ServiceRequest tests.
- name: DiagnosticReport
description: Structured lab and radiology results.
- name: Observation
description: Individual result observations.
- name: DocumentReference
description: Clinical document metadata.
- name: Binary
description: Raw clinical document content.
- name: Coverage
description: Patient insurance coverage / eligibility.
- name: Practitioner
description: Ordering and rendering providers.
paths:
/metadata:
get:
operationId: getCapabilityStatement
tags:
- CapabilityStatement
summary: Retrieve the FHIR server CapabilityStatement.
description: >-
Returns the FHIR R4 CapabilityStatement describing supported
resources, search parameters, operations, and authentication.
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/CapabilityStatement'
/Patient:
get:
operationId: searchPatients
tags:
- Patient
summary: Search Patient resources.
parameters:
- $ref: '#/components/parameters/identifier'
- $ref: '#/components/parameters/name'
- name: birthdate
in: query
schema:
type: string
format: date
- name: gender
in: query
schema:
type: string
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of matching Patient resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
post:
operationId: createPatient
tags:
- Patient
summary: Create a Patient resource.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
responses:
'201':
description: Created
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
/Patient/{id}:
get:
operationId: readPatient
tags:
- Patient
summary: Read a Patient resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
'404':
$ref: '#/components/responses/OperationOutcome'
put:
operationId: updatePatient
tags:
- Patient
summary: Update a Patient resource.
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
/Patient/{id}/$everything:
get:
operationId: patientEverything
tags:
- Patient
summary: Retrieve all records for a patient.
description: >-
FHIR $everything operation returning a Bundle of all resources in the
patient compartment, including federated records retrieved across the
national exchange network.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: A FHIR Bundle of patient-scoped resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
'202':
description: >-
Accepted - federated retrieval is in progress; poll the returned
location for completed, partial, or failed status.
/RequestGroup:
post:
operationId: createRequestGroup
tags:
- RequestGroup
summary: Submit a diagnostic order.
description: >-
Creates a RequestGroup parent order that nests one or more
ServiceRequest resources (individual tests) for submission to a
participating diagnostic laboratory or radiology partner.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/RequestGroup'
responses:
'201':
description: Created
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/RequestGroup'
get:
operationId: searchRequestGroups
tags:
- RequestGroup
summary: Search RequestGroup orders.
parameters:
- $ref: '#/components/parameters/patient'
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of RequestGroup resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/RequestGroup/{id}:
get:
operationId: readRequestGroup
tags:
- RequestGroup
summary: Read a RequestGroup order by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/RequestGroup'
/ServiceRequest:
get:
operationId: searchServiceRequests
tags:
- ServiceRequest
summary: Search ServiceRequest resources.
parameters:
- $ref: '#/components/parameters/patient'
- name: status
in: query
schema:
type: string
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of ServiceRequest resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
post:
operationId: createServiceRequest
tags:
- ServiceRequest
summary: Create a ServiceRequest resource.
requestBody:
required: true
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/ServiceRequest'
responses:
'201':
description: Created
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/ServiceRequest'
/ServiceRequest/{id}:
get:
operationId: readServiceRequest
tags:
- ServiceRequest
summary: Read a ServiceRequest resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/ServiceRequest'
/DiagnosticReport:
get:
operationId: searchDiagnosticReports
tags:
- DiagnosticReport
summary: Search DiagnosticReport resources.
parameters:
- $ref: '#/components/parameters/patient'
- name: category
in: query
schema:
type: string
- name: date
in: query
schema:
type: string
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of DiagnosticReport resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/DiagnosticReport/{id}:
get:
operationId: readDiagnosticReport
tags:
- DiagnosticReport
summary: Read a DiagnosticReport resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/DiagnosticReport'
/Observation:
get:
operationId: searchObservations
tags:
- Observation
summary: Search Observation resources.
parameters:
- $ref: '#/components/parameters/patient'
- name: code
in: query
schema:
type: string
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of Observation resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/DocumentReference:
get:
operationId: searchDocumentReferences
tags:
- DocumentReference
summary: Search DocumentReference resources.
parameters:
- $ref: '#/components/parameters/patient'
- name: type
in: query
schema:
type: string
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of DocumentReference resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/DocumentReference/{id}:
get:
operationId: readDocumentReference
tags:
- DocumentReference
summary: Read a DocumentReference resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/DocumentReference'
/Binary/{id}:
get:
operationId: readBinary
tags:
- Binary
summary: Retrieve raw document content.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: The document content (CCDA, PDF, or other format).
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Binary'
application/octet-stream:
schema:
type: string
format: binary
/Coverage:
get:
operationId: searchCoverage
tags:
- Coverage
summary: Search Coverage resources.
parameters:
- $ref: '#/components/parameters/patient'
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of Coverage resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/Coverage/{id}:
get:
operationId: readCoverage
tags:
- Coverage
summary: Read a Coverage resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Coverage'
/Practitioner:
get:
operationId: searchPractitioners
tags:
- Practitioner
summary: Search Practitioner resources.
parameters:
- $ref: '#/components/parameters/identifier'
- $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/count'
responses:
'200':
description: A FHIR Bundle of Practitioner resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
/Practitioner/{id}:
get:
operationId: readPractitioner
tags:
- Practitioner
summary: Read a Practitioner resource by id.
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Practitioner'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth 2.0 bearer access token. Obtain a token using the client
credentials issued during onboarding via the Health Gorilla OAuth 2.0
token endpoint, then pass it as `Authorization: Bearer {token}`.
parameters:
id:
name: id
in: path
required: true
description: The logical id of the resource.
schema:
type: string
identifier:
name: identifier
in: query
description: A resource identifier (system|value).
schema:
type: string
name:
name: name
in: query
description: A portion of the name.
schema:
type: string
patient:
name: patient
in: query
description: Reference to the subject Patient (e.g. Patient/{id}).
schema:
type: string
count:
name: _count
in: query
description: Number of results per page.
schema:
type: integer
responses:
OperationOutcome:
description: A FHIR OperationOutcome describing an error.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/OperationOutcome'
schemas:
Resource:
type: object
properties:
resourceType:
type: string
id:
type: string
meta:
type: object
Bundle:
type: object
properties:
resourceType:
type: string
example: Bundle
type:
type: string
example: searchset
total:
type: integer
link:
type: array
items:
type: object
properties:
relation:
type: string
url:
type: string
entry:
type: array
items:
type: object
properties:
fullUrl:
type: string
resource:
type: object
Patient:
type: object
properties:
resourceType:
type: string
example: Patient
id:
type: string
identifier:
type: array
items:
type: object
name:
type: array
items:
type: object
gender:
type: string
birthDate:
type: string
format: date
address:
type: array
items:
type: object
telecom:
type: array
items:
type: object
ServiceRequest:
type: object
properties:
resourceType:
type: string
example: ServiceRequest
id:
type: string
status:
type: string
example: active
intent:
type: string
example: order
code:
type: object
subject:
type: object
requester:
type: object
performer:
type: array
items:
type: object
RequestGroup:
type: object
properties:
resourceType:
type: string
example: RequestGroup
id:
type: string
status:
type: string
example: active
intent:
type: string
example: order
subject:
type: object
author:
type: object
action:
type: array
items:
type: object
properties:
resource:
type: object
description: Reference to a nested ServiceRequest.
DiagnosticReport:
type: object
properties:
resourceType:
type: string
example: DiagnosticReport
id:
type: string
status:
type: string
category:
type: array
items:
type: object
code:
type: object
subject:
type: object
effectiveDateTime:
type: string
format: date-time
result:
type: array
items:
type: object
description: References to Observation resources.
presentedForm:
type: array
items:
type: object
Observation:
type: object
properties:
resourceType:
type: string
example: Observation
id:
type: string
status:
type: string
code:
type: object
subject:
type: object
valueQuantity:
type: object
referenceRange:
type: array
items:
type: object
DocumentReference:
type: object
properties:
resourceType:
type: string
example: DocumentReference
id:
type: string
status:
type: string
type:
type: object
subject:
type: object
content:
type: array
items:
type: object
properties:
attachment:
type: object
properties:
contentType:
type: string
url:
type: string
Binary:
type: object
properties:
resourceType:
type: string
example: Binary
id:
type: string
contentType:
type: string
data:
type: string
format: byte
Coverage:
type: object
properties:
resourceType:
type: string
example: Coverage
id:
type: string
status:
type: string
beneficiary:
type: object
payor:
type: array
items:
type: object
subscriberId:
type: string
Practitioner:
type: object
properties:
resourceType:
type: string
example: Practitioner
id:
type: string
identifier:
type: array
items:
type: object
name:
type: array
items:
type: object
CapabilityStatement:
type: object
properties:
resourceType:
type: string
example: CapabilityStatement
status:
type: string
fhirVersion:
type: string
example: 4.0.1
rest:
type: array
items:
type: object
OperationOutcome:
type: object
properties:
resourceType:
type: string
example: OperationOutcome
issue:
type: array
items:
type: object
properties:
severity:
type: string
code:
type: string
diagnostics:
type: string