Patient

The FHIR R4 Patient resource represents demographic and administrative information about an individual receiving healthcare services. It is the central reference point for nearly all clinical resources in FHIR.

Use Cases

Register a new patient in the Health Gorilla network
Retrieve or match patient demographics across systems
Link clinical data (e.g., labs, medications, encounters) to the patient record

Base URLs

Production: https://api.healthgorilla.com/fhir/R4/Patient
Sandbox: https://sandbox.healthgorilla.com/fhir/R4/Patient

Required Scopes

patient.read for GET
patient.write for POST and PUT

For details, go to: OAuth 2.0 Authentication.

Search Parameters

Patient supports three search forms, and a request must use one of them:

identifier on its own.
A demographic search using any combination of the demographic filters.
A search on _lastUpdated on its own.

Parameter	Required	Description
`identifier`	Required in the identifier search	Returns the patient carrying the given identifier.
`_lastUpdated`	Required in its own search form	Filters on when the record was last written in the Health Gorilla FHIR server. Accepts a comparison prefix, for example `ge2025-01-01`.
`given`	No	Filters on the given name.
`family`	No	Filters on the family name.
`name`	No	Filters on any part of the name.
`gender`	No	Filters on the administrative gender.
`birthdate`	No	Filters on the date of birth.
`address-postalcode`	No	Filters on the postal code in the patient address.
`organization.identifier`	No	Returns the patients belonging to the organization carrying the given identifier. In STU3 this parameter is named `organization`.
`_offset`	No	Skips the given number of results.
`_count`	No	Limits the number of results returned per page.

Only the postal code is searchable in the address. A general address parameter isn't supported. To retrieve a patient by FHIR id, use a read rather than a search.

Resource Attributes

Attribute	Description	Example	FHIR Data Type	Required
`id`	Unique FHIR ID for the patient	`pat-78910`	`id`	Yes
`identifier`	External patient IDs	MRN: `123456`, SSN: `999-12-3456`	`Identifier[]`	No
`name`	Full patient name	`John Doe`	`HumanName[]`	Yes
`gender`	Patient's gender	`male`	`code`	No
`birthDate`	Date of birth	`1985-06-21`	`date`	No
`telecom`	Contact information	`555-555-5555`, `[email protected]`	`ContactPoint[]`	No
`address`	Physical or mailing address	`123 Main St, Sunnyvale, CA`	`Address[]`	No
`deceasedBoolean`	Indicates if the patient is deceased	`false`, `true`	`boolean`	No
`active`	Whether the patient record is active	`true`	`boolean`	No
`managingOrganization`	Organization responsible for the patient	`Organization/{id}`	`Reference(Organization)`	No
`communication.language`	Preferred language	`en`, `es`	`CodeableConcept`	No
`generalPractitioner`	Reference to the primary care provider	`Practitioner/{id}`	`Reference`	No

Events

Patient records emit webhook events on create and update. For setup and payload format, see Webhooks & Polling.

Errors

All Patient operations return FHIR OperationOutcome for structured error responses. See Error Handling.

More Information

Patient guide on the developer portal — workflows, network choice, Patient360 patterns
HL7 FHIR Patient specification