Edvak Docs
HomeFHIR APICCDA API
HomeFHIR APICCDA API
LinkedIn
  1. API Usage Guidelines
  • Getting Started
    • Introduction
    • Supported Standards, Frameworks & API Versions
    • Standardized API Details – Patient and Population Services
    • Environment Endpoints
    • Errors and Exceptions
  • Authentication & Authorization
    • Overview – Authorization & Security Standards
    • Authorization
      • Well-known configuration
      • Authorize
      • Request
      • Revoke
      • Introspect
  • Developer Onboarding
    • App Registration & Credentials
  • API Usage Guidelines
    • FHIR API Interaction Conventions
  • US Core & USCDI Mapping
    • Overview
  • APIs
    • Allergies and Intolerances
      • By Patient ID
      • By Resource ID
    • Assessment and Plan of Treatment
      • By Patient and Category
    • Care Team Members
      • Care Teams
        • By Patient and Status
        • By Patient and Role
      • Related Person
        • By ID
        • By Patient
      • Practitioner
        • By Name
        • By Resource ID
        • By Identifier
      • Practioner Role
        • By Specialty
        • By Practitioner ID
        • By Practitioner Identifier
        • By Practitioner Name
      • Location
        • By Name
        • By Address
        • By City
        • By State
        • By Postal Code
      • Organization
        • By Name
        • By Address
    • Clinical Notes
      • Document References
        • By ID
        • By Patient
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient and Type
        • By Patient and Status
        • By Patient, Type, and Period
      • Diagnostic Report
        • By Patient ID
        • By Patient and Category
        • By Patient and Code
        • By Patient, Category, and Date
        • By Patient and Status
    • Goals
      • Get Goals by Patient ID
      • Get Goal by ID
      • Get Goals by Patient and Lifecycle Status
      • Get Goals by Patient and Target Date
      • Get Goals by Patient and Description
      • Get Diagnostic Reports by Patient, Code, and Date
    • Clinical Tests
      • Observation
        • By Patient and Category
        • By Patient and Code
        • By Patient, Code, and Date
        • By Patient, Category, and Date
        • By Patient, Category, and Status
      • Lab Diagnostic Report
        • By Patient
        • By Patient and Code
        • By Patient, Code, and Date
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient and Status
    • Diagnostic Imaging
      • Imaging Observations
        • By Patient
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient, Category, and Status
        • By Patient and Code
        • By Patient, Code and Date
    • Encounter Information
      • Encounter
        • By ID
        • By Patient ID
        • By Patient and Date Range
        • By Identifier
        • By Patient and Class
        • By Patient and Type
        • By Patient and Location
        • By Patient and Status
        • By Patient and Discharge Disposition
      • Encounter Diagnosis
        • By Patient ID
        • By Patient ID and Clinical Status
        • By Patient ID and Category
        • By Patient ID and Code
        • By Patient ID and Asserted Date
        • By Patient ID, Category, and Encounter
        • By Patient ID and Onset Date
        • By Patient ID and Recorded Date
        • By Patient ID and Abatement Date
    • Group
      • By ID
      • By $export (Group-level Bulk Export)
    • Health Concerns
      • By Patient
      • By Patient and Clinical Status
      • By Patient and Category
      • By Patient and Category and Encounter
      • By Patient and Code
      • By Patient and Asserted Date
      • By Patient and Onset Date
      • By Patient and Recorded Date
      • By Patient and Abatement Date
    • Implantable Devices
      • By Patient
      • By ID
      • By Patient and Type
    • Immunizations
      • By ID
      • By Patient
      • By Patient and Date
      • By Patient and Status
    • Laboratory
      • Laboratory Result Observation
        • By ID
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient, Category, and Status
        • By Patient and Code
        • By Patient, Code, and Date
    • Medications
      • Medications
        • By ID
        • By Patient
      • Medication Request
        • Get MedicationRequests by Patient
        • Get MedicationRequest by ID
        • Get MedicationRequests by Patient and Intent
        • Get MedicationRequests by Patient, Intent, and Encounter
        • Get MedicationRequests by Patient, Intent, and AuthoredOn Date
    • Patient Demographics
      • Patient
        • Get Patient by ID
        • Get Patient by Identifier
        • Get Patient by Name
        • Get Patient by Birthdate and Name
        • Get Patient by Gender and Name
        • Get Patient by Birthdate and Family Name
      • Observation Sexual Orientation
        • Get Observations by Patient ID
        • Get Observation by ID
        • Get Observations by Patient and Code
        • Get Observations by Patient, Code, and Date
        • Get Observations by Patient, Code, and Date
    • Procedures
      • Procedure
        • Get Procedures by Patient
        • Get Procedure by ID
        • Get Procedures by Patient and Date
        • Get Procedures by Patient and Status
        • Get Procedures by Patient, Code, and Date
      • Service Request
        • Get ServiceRequests by Patient
        • Get ServiceRequest by ID
        • Get ServiceRequests by Patient and Category
        • Get ServiceRequests by Patient and Code
        • Get ServiceRequests by Patient, Category, and Authored Date
        • Get ServiceRequests by Patient, Code, and Authored Date
        • Get ServiceRequests by Patient and Status
    • Provenance
      • Provenance
        • Get Provenance by ID
        • Get resource and Provenance using _revinclude
    • Smoking Status
      • Smoking Status
        • Get Observation by ID
        • Get Observations by Patient
        • Get Smoking Status by Patient and Code
    • Vital Signs
      • Vital Signs
        • Get Observation by ID
        • Get Observations by Patient and Category
        • Get Observations by Patient and Code
        • Get Observations by Patient, Category, and Date
        • Get Observations by Patient, Category, and Status
        • Get Observations by Patient, Code, and Date
  • Legal & Compliance
    • API Terms of Use
  1. API Usage Guidelines

FHIR API Interaction Conventions

FHIR APIs follow consistent interaction patterns for reading, searching, and exchanging clinical data. This guide explains how to structure requests, use UCUM units in observations, and apply correct syntax for both direct reads and parameterized searches.

Representing Quantities with UCUM#

FHIR uses the UCUM (Unified Code for Units of Measure) standard for expressing physical quantities, particularly in clinical observations such as lab results and vital signs.

When a valid UCUM unit is known:#

"valueQuantity": {
  "value": 98.6,
  "unit": "°F",
  "system": "http://unitsofmeasure.org",
  "code": "°F"
}

When a UCUM code is not available (free text only):#

"valueQuantity": {
  "value": 75,
  "unit": "bpm"
}

When no units are available:#

"valueQuantity": {
  "value": 120
}
US Core profiles (e.g. Vital Signs, Lab Results) expect binding to UCUM codes. If unavailable, fallback to unit alone is allowed, but discouraged for certified use.

Fetching a Resource (Read Interaction)#

FHIR defines a standard syntax for retrieving individual resources using HTTP GET. This follows the pattern:
GET [base-url]/[Resource-type]/[id]{?parameters}

Syntax Breakdown:#

ComponentDescriptionExample
GETThe HTTP method used to retrieve dataGET /Patient/12345
[base-url]Root service endpoint for the API (Sandbox)https://fhir-dev.fhir.edvak.com/fhir
[Resource-type]Type of FHIR resource being accessedPatient
[id]Logical ID of the resource12345
{?parameters}Optional query parameters to filter/modify the request?name=John&birthdate=1980-01-01

Example:#

GET https://fhir-dev.fhir.edvak.com/fhir/Patient/12345

Performing a Search (Query Interaction)#

To retrieve a set of resources matching specific criteria, use the FHIR search interaction. All searches are executed with HTTP GET and follow this pattern:
GET [base-url]/[Resource-type]?[search-parameters]

Example:#

GET https://fhir-dev.fhir.edvak.com/fhir/Observation?patient=12345&code=29463-7

Search Syntax Components:#

SyntaxMeaningExample
parameter=valueBasic key-value pair searchname=John
param1=val1&param2=val2Multiple parameters joined by ANDgender=male&birthdate=1980-01-01
parameter=val1,val2Comma-separated values = logical ORstatus=active,inactive
parameter:modifier=valueModifier to refine the matchname:contains=John
parameter=comparatorvalueUse comparators like gt, lt, ge, lebirthdate=ge2000-01-01

Token Search Format:#

[system]|[code]
Example:
code=http://loinc.org|29463-7

Reference Search Format:#

[Type/][id]
Example:
patient=Patient/12345

Date Search Format:#

date={gt|lt|ge|le}[YYYY-MM-DD]
Example:
date=ge2024-01-01
If no comparator is used, eq (equals) is assumed.

SMART on FHIR Search Behavior#

When using SMART on FHIR v2.0.0, especially in patient-scoped access (e.g. patient/Observation.read), the system automatically applies a filter limiting results to the authorized patient. This means:
...implicitly behaves like:
This is handled by the authorization layer and does not need to be explicitly added by the client in patient-scoped access contexts.
Previous
App Registration & Credentials
Next
Overview
Built with