Provenance

The FHIR R4 Provenance resource tracks the origin, authorship, and transmission of clinical data. It identifies the agents, systems, and source documents involved in creating or importing a given resource. Health Gorilla automatically generates Provenance records for key clinical data to support data lineage, audit trails, and trustworthiness assessments.

Use Cases

  • Audit who created or imported a clinical record
  • Identify the source system or provider organization that authored a result
  • Investigate how a resource was derived or transmitted into the system

Base URLs

Authentication

All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.

Required Scopes

  • provenance.read for GET

For more information, go to: OAuth 2.0 Authentication.

Supported Methods

Provenance Methods

MethodOperationDescription
GETRead ProvenanceRetrieves a specific Provenance record by its FHIR ID.
GETSearch ProvenanceSearches for Provenance records referencing a target resource or patient.

Note: POST, PUT, and DELETE are not supported. Provenance is system-managed.

Frequently Used Search Parameters

ParameterDescriptionFHIR Value Set / Example ValuesFHIR Data TypeRequired
targetFilters by the resource the provenance refers toObservation/{id}, DocumentReference/{id}ReferenceYes (recommended)
patientFilters by the patient related to the target resourcePatient/{id}ReferenceNo
recordedFilters by the timestamp the provenance was recordedge2023-01-01dateNo
agentFilters by the actor responsible for the activityPractitioner/{id}, Organization/{id}ReferenceNo
_idFilters by the Provenance FHIR resource IDProvenance/{id}tokenNo

Commonly Returned Resource Attributes

AttributeDescriptionExample ValuesFHIR Data TypeRequired
idUnique FHIR ID for the Provenance recordprov-123456idYes
targetResources the provenance applies toObservation/{id}, DocumentReference/{id}Reference[]Yes
recordedTimestamp when the activity was recorded2024-01-05T14:22:01ZinstantYes
agentActor(s) responsible for the activityPractitioner, Organization, or system IDProvenance.Agent[]Yes
agent.typeType of participant in the eventperformerCodeableConceptNo
agent.whoReference to the agent (person or system)Practitioner/{id}ReferenceYes
entitySource data or resource used to construct the targetDocumentReference/{id}, Observation/{id}Provenance.Entity[]No
entity.roleRole of the entity in the provenance eventsource, derivationcodeNo
signatureDigital signature for validation (if present)base64-encoded digital signatureSignature[]No

Linked Resource Types

Health Gorilla automatically creates Provenance records for the following resource types:

  • AllergyIntolerance
  • CarePlan
  • Condition
  • DeviceUseStatement
  • DiagnosticReport
  • Encounter
  • FamilyMemberHistory
  • Goal
  • Immunization
  • MedicationRequest
  • MedicationDispense
  • NutritionOrder
  • Observation (vitals, functional, social history)
  • Procedure
  • DocumentReference

Webhooks

Provenance resources are not directly pushed via webhooks, but may be referenced in webhook-triggering payloads (e.g., DocumentReference, Observation, DiagnosticReport).

For more information, go to: Webhooks & Polling.

Error Handling

All Provenance operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured error responses.
For more information, go to: Error Handling.

Additional Resources

HL7 FHIR Provenance