The FHIR R4 ServiceRequest resource represents a request for a clinical service to be performed. This includes lab tests, imaging, procedures, referrals, consults, and other services. It is commonly used to document orders initiated by clinicians as part of diagnostic or treatment workflows.
Use Cases
- Order laboratory tests or radiology studies
- Refer a patient to a specialist or external facility
- Track the status of a service requested during an encounter
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/ServiceRequest
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/ServiceRequest
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
servicerequest.readfor GETservicerequest.writefor POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read ServiceRequest | Retrieves a specific ServiceRequest record by its FHIR ID. |
GET | Search ServiceRequest | Searches for ServiceRequest records associated with a patient. |
POST | Create ServiceRequest | Submits a new ServiceRequest record to the Health Gorilla FHIR server. |
GET | Download ServiceRequest PDF | Retrieves a PDF version of the ServiceRequest document, formatted for human-readable display. |
Search Parameters
The Health Gorilla ServiceRequest endpoint represents referrals. That is why category must carry the SNOMED referral code, and why it is required for API versions from August 2022 onward.
| Parameter | Required | Description |
|---|---|---|
category | Yes, for API versions from August 2022 | Must be the SNOMED referral code. No other value is accepted. |
patient | No | The patient whose referrals you want, as Patient/{id}. You can also search by a patient identifier using patient.identifier. |
status | No | Filters on the referral status. |
_lastUpdated | No | Filters on when the record was last written in the Health Gorilla FHIR server. Accepts a comparison prefix, for example ge2025-01-01. |
_offset | No | Skips the given number of results. |
_count | No | Limits the number of results returned per page. |
The search also accepts _include=Referral:subject, _include=Referral:requester.agent, _include=Referral:requester.onBehalfOf, _include=Referral:recipient, and _include=Referral:supportingInfo. The Referral prefix reflects how Health Gorilla names the referral resource internally and is not a typo.
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
id | Unique FHIR ID for the service request | servicerequest-98765 | id | Yes |
status | Current status of the request | active | code | Yes |
intent | Purpose of the request | order, plan | code | Yes |
code | Type of service being requested | LOINC or SNOMED CT | CodeableConcept | Yes |
subject | The patient associated with the request | Patient/{id} | Reference(Patient) | Yes |
requester | Who initiated the request | Practitioner/{id}, Organization/{id} | Reference | No |
performer | Intended individual or organization to fulfill the order | Organization/{id}, Practitioner/{id} | Reference[] | No |
reasonCode | Reason for the service | chest pain, screening | CodeableConcept[] | No |
occurrence | Scheduled time for the service | 2024-01-15T09:00:00-07:00 | dateTime | No |
authoredOn | Date the request was created | 2023-12-01T14:32:00-08:00 | dateTime | No |
note | Additional notes or comments | "Urgent referral requested" | Annotation[] | No |
Webhooks
ServiceRequest records can trigger webhook notifications when new requests are submitted or existing requests are updated. These are useful for tracking pending services or orders that require action. For more information, go to: Webhooks and Polling
Error Handling
All ServiceRequest operations follow standard Health Gorilla error handling, including structured FHIR OperationOutcome responses. For more information, go to: Error Handling