Phoenix Ortho FHIR API
ONC § 170.315(g)(7), § 170.315(g)(9), & § 170.315(g)(10) Standardized API
● Production Live ONC § 170.315(g)(7) HL7 FHIR R4 v4.0.1 US Core 3.1.1 & 6.1.0 SMART v1 & v2

Phoenix Ortho FHIR API Documentation

Complete public developer documentation for the Phoenix Ortho EHR Fast Healthcare Interoperability Resources (FHIR®) API, certified under ONC 2015 Edition Cures Update § 170.315(g)(7) Patient Selection, § 170.315(g)(9) All Data Request, and § 170.315(g)(10) Standardized API.

🏥 Standards-Based Interoperability

Built upon HL7® FHIR® Release 4 (v4.0.1) and fully conforms to US Core Implementation Guides v3.1.1 and v6.1.0, enabling patients and clinicians to securely access health records using any modern healthcare app.

🔒 SMART on FHIR Certified Security

Supports SMART App Launch 1.0.0 and 2.0.0 including Standalone Launch with PKCE (S256), EHR App Launch, and SMART Backend Services with asymmetric client assertions (RFC 7523 private_key_jwt).

📊 Population-Level Bulk Data

Empowers authorized population health queries and research analytics through asynchronous FHIR Bulk Data Access specifications ($export) generating multi-resource newline-delimited JSON (NDJSON) datasets.

Standards & Regulatory Conformance

The Phoenix Ortho FHIR API is designed, implemented, and certified in accordance with United States Office of the National Coordinator for Health Information Technology (ONC) Health IT Certification criteria:

Standard / Regulation Version Conformance Specification & Purpose
ONC § 170.315(g)(7) 2015 Cures Update Application access – patient selection (Demographic search query and SMART on FHIR patient launch context returning unique patient ID and security token)
ONC § 170.315(g)(10) 2015 Cures Update Standardized API for patient and population services (Single patient and population export)
ONC § 170.315(g)(9) 2015 Cures Update Application access – all data request (Continuity of Care Document C-CDA XML generation)
ONC § 170.315(b)(1) 2015 Cures Update Transitions of Care – creating, transmitting, and validating C-CDA R2.1 documents
HL7® FHIR® Base Release 4 (v4.0.1) Core RESTful FHIR specification, data types, JSON representations, and search parameter framework
US Core Implementation Guide v3.1.1 & v6.1.0 United States Core Data for Interoperability (USCDI v1 & v3) profile constraints, terminology, and search rules
SMART App Launch IG v1.0.0 & v2.0.0 OAuth 2.0 authorization, PKCE S256, OpenID Connect, granular scopes, launch contexts
FHIR Bulk Data Access IG v1.0.0 & v2.0.0 Asynchronous Group and Patient population export producing NDJSON files

Base Endpoints & Discovery

Developers can interact with the Phoenix FHIR API via the production API Gateway. All communication is strictly encrypted over TLS 1.2 or TLS 1.3.

Endpoint Role Public Production URL Description
FHIR R4 Server Base https://phoenixfhir-apim.azure-api.net/smart Root URL for all FHIR resource interactions (Patient, Observation, Condition, etc.)
SMART Metadata https://phoenixfhir-apim.azure-api.net/smart/metadata FHIR CapabilityStatement describing supported resources, operations, and US Core profiles
SMART Configuration https://phoenixfhir-apim.azure-api.net/smart/.well-known/smart-configuration Discovery document for OAuth endpoints, capabilities, and supported scopes
OpenID Configuration https://phoenixfhir-apim.azure-api.net/smart/.well-known/openid-configuration OIDC discovery endpoint for issuer and token validation parameters
JWKS Public Keys https://phoenixfhir-apim.azure-api.net/auth/.well-known/jwks.json Public JSON Web Key Set used to verify token signatures (RS256)
OAuth Authorization https://phoenixfhir-apim.azure-api.net/auth/authorize Initiates interactive user authorization and patient launch consent
OAuth Token Exchange https://phoenixfhir-apim.azure-api.net/auth/token Exchanges authorization codes, refresh tokens, and client assertions for access tokens
Token Introspection https://phoenixfhir-apim.azure-api.net/auth/introspect RFC 7662 token active check and scope introspection endpoint
Token Revocation https://phoenixfhir-apim.azure-api.net/auth/revoke RFC 7009 token revocation endpoint for access and refresh tokens
Patient Selection (Demographic Search) https://phoenixfhir-apim.azure-api.net/smart/Patient ONC § 170.315(g)(7) Demographic search endpoint (family, given, birthdate, gender, identifier) returning FHIR Patient Bundle with unique ID
Patient Selection (SMART Launch) https://phoenixfhir-apim.azure-api.net/auth/authorize?scope=launch/patient... ONC § 170.315(g)(7) Patient Selection via OAuth 2.0 authorization returning patient context token parameter
C-CDA Generation API https://phoenixfhir-sync-func.azurewebsites.net/api/generate-ccda/{scenario} ONC § 170.315(g)(9) All Data Request C-CDA XML generation endpoint
💡 Interactive Verification

Both /metadata and /.well-known/smart-configuration are publicly available without authentication. You can query them right now in your browser or terminal to inspect the live CapabilityStatement.

5-Minute Quickstart Tutorial

This quickstart demonstrates how to query a patient's clinical conditions using a registered test client and standard OAuth 2.0 PKCE flow.

Step 1: Check System Capabilities

Retrieve the FHIR CapabilityStatement to verify supported interactions:

# Fetch the live CapabilityStatement
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/metadata" \
  -H "Accept: application/fhir+json"

Step 2: Authenticate & Obtain Access Token

For patient-facing or standalone apps, generate a cryptographic PKCE code_verifier (64 characters) and SHA-256 code_challenge, then direct the user to the authorize endpoint:

# 1. Direct browser to Authorization URL
https://phoenixfhir-apim.azure-api.net/auth/authorize?
  response_type=code&
  client_id=test_client&
  redirect_uri=https://example.com/callback&
  scope=openid+fhirUser+offline_access+patient/*.read&
  state=xyzState123&
  aud=https://phoenixfhir-apim.azure-api.net/smart&
  code_challenge=E9Melhoa2OwvFrGMTJguCH5rtx64ZnJSmv38DCyLIOc&
  code_challenge_method=S256

# 2. Exchange authorization code for Access Token
curl -X POST "https://phoenixfhir-apim.azure-api.net/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_RECEIVED_AT_CALLBACK" \
  -d "redirect_uri=https://example.com/callback" \
  -d "client_id=test_client" \
  -d "code_verifier=VERIFIER_STRING_BEFORE_HASHING"

Step 3: Query Clinical Resources

Pass the Bearer token in the Authorization header and request application/fhir+json:

# Query Patient Demographics
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/Patient/phoenixortho.net-PAT1000000013" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

# Search Conditions for this Patient
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/Condition?patient=phoenixortho.net-PAT1000000013" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

SMART on FHIR Authorization Architecture

The Phoenix Ortho FHIR API implements the SMART on FHIR specification. Authorization decisions and tokens are managed by a dedicated OAuth 2.0 authorization server providing cryptographic JWT verification, granular scope enforcement, token introspection, and instant revocation.

SMART Core Capabilities Supported

launch-standalone launch-ehr client-public client-confidential-symmetric client-confidential-asymmetric sso-openid-connect context-standalone-patient context-ehr-patient permission-offline permission-patient permission-user permission-v1 permission-v2 authorize-post

1. Standalone App Launch (PKCE)

Recommended for mobile applications, single-page web applications (SPAs), and third-party patient portal apps connecting directly without EHR context. Uses RFC 7636 Proof Key for Code Exchange (PKCE) to prevent authorization code interception.

Authorization Request Parameters

Parameter Required Type Description
response_type Yes String Must be code
client_id Yes String Your registered application client identifier (e.g., test_client)
redirect_uri Yes URI Must strictly match one of your application's pre-registered redirect URIs
scope Yes String Space-delimited list of requested SMART scopes (e.g., openid fhirUser offline_access patient/*.read)
state Yes String Opaque value generated by your app to maintain state and mitigate CSRF
aud Yes URI FHIR Base URL: https://phoenixfhir-apim.azure-api.net/smart
code_challenge Yes String Base64URL-encoded SHA-256 hash of your randomly generated code_verifier
code_challenge_method Yes String Must be S256

2. EHR App Launch Flow

Used when launching an application embedded directly inside the Phoenix Ortho EHR user interface. The EHR supplies a unique launch identifier and the FHIR base URL (iss) as query parameters to your application's launch URL.

ℹ️ EHR Launch Execution

Upon receiving ?launch=xyz&iss=..., your app requests authorization including launch in the scope parameter and passes the received launch token. When user consent completes, the access token response will include the active patient ID and encounter ID in the launch context.

3. SMART Backend Services (Asymmetric Client Auth)

Designed for automated background jobs, system-to-system integrations, and population-level Bulk Data Export ($export) without interactive user logins. Conforms to SMART Backend Services authorization using asymmetric cryptographic keys.

Client Assertion Specification

The client creates a signed JSON Web Token (JWT) with the following claims, signed using an RSA (RS256/RS384) or ECDSA (ES256/ES384) private key whose public key is registered in your application's JWKS:

JWT Claim Value / Description
iss Client's registered client_id
sub Client's registered client_id
aud Token endpoint: https://phoenixfhir-apim.azure-api.net/auth/token
jti Unique token identifier (UUIDv4) to prevent replay attacks
exp Expiration timestamp (UTC epoch seconds, max 5 minutes from issue)
Backend Services Token Request (cURL)
curl -X POST "https://phoenixfhir-apim.azure-api.net/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=eyJhbGciOiJSUzI1NiIs..." \
  -d "scope=system/*.read"

Supported Scopes Reference

Phoenix Ortho FHIR API supports granular resource-level scopes as well as wildcard scopes across Patient, User, and System contexts:

Scope Target Context Description & Permissions
openid Identity Enables OpenID Connect user identity verification
fhirUser Identity Returns URL of FHIR resource representing current user (Practitioner or Patient)
offline_access Token Lifecycle Requests a refresh token for long-lived offline data synchronization
launch / launch/patient Context Transfers EHR launch context / active patient context to the client
patient/*.read / patient/*.rs Patient Context Read-only access to all clinical resources for the currently authorized patient
patient/[Resource].read Patient Context Granular read access to a specific resource (e.g., patient/Observation.read)
user/*.read / user/*.rs Clinician Context Read access to all clinical records authorized for the authenticated clinician
system/*.read / system/*.rs System Context Full read access across all patient populations for backend services / bulk export

Token Introspection & Revocation

In accordance with ONC § 170.315(g)(10) and RFC 7662 / RFC 7009, clients and resource servers can inspect token status and immediately revoke active access or refresh tokens.

1. Token Introspection (RFC 7662)

POST https://phoenixfhir-apim.azure-api.net/auth/introspect

Introspection Request (cURL)
curl -X POST "https://phoenixfhir-apim.azure-api.net/auth/introspect" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=YOUR_ACCESS_OR_REFRESH_TOKEN"

2. Token Revocation (RFC 7009)

POST https://phoenixfhir-apim.azure-api.net/auth/revoke

Revocation Request (cURL)
curl -X POST "https://phoenixfhir-apim.azure-api.net/auth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "client_id=test_client"

Developer App Registration

Under ONC § 170.315(g)(10), developers can register new SMART on FHIR client applications via our developer registration endpoint without unnecessary delays or proprietary agreements.

POST /auth/register-app
Registration Endpoint

Register a new client application with redirect URIs and JWKS public key endpoints.

Payload Example (JSON)
{
  "client_name": "My Health Dashboard",
  "redirect_uris": ["https://myhealthapp.com/oauth/callback"],
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://myhealthapp.com/.well-known/jwks.json",
  "grant_types": ["authorization_code", "refresh_token", "client_credentials"],
  "scope": "openid fhirUser offline_access patient/*.read"
}

US Core Resource Catalog

USCDI v1 & v3 Compliant

The Phoenix Ortho FHIR API exposes complete clinical and administrative resources according to the US Core Implementation Guide (v3.1.1 and v6.1.0). Each resource profile includes required search parameters, data elements, and code systems.

GET /smart/Patient/{id}
US Core Patient

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient

Provides patient demographics including Legal Name, Date of Birth, Gender, Address, Telecom, Race & Ethnicity (OMB), Birth Sex, and Preferred Language.

Supported Search Parameters

  • _id: Logical resource ID
  • identifier: Medical Record Number (MRN) or system ID
  • name: Patient given or family name
  • family: Patient last name
  • given: Patient first name
  • birthdate: Patient birth date (supports eq, ge, le)
  • gender: Administrative gender
Sample Patient Response (JSON)
{
  "resourceType": "Patient",
  "id": "phoenixortho.net-PAT1000000013",
  "meta": {
    "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"]
  },
  "identifier": [
    {
      "system": "urn:oid:2.16.840.1.113883.19.5",
      "value": "PAT1000000013"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Easttom",
      "given": ["Chuck"]
    }
  ],
  "gender": "male",
  "birthDate": "1978-04-12",
  "address": [
    {
      "line": ["123 Ortho Way"],
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75001",
      "country": "USA"
    }
  ]
}
GET /smart/AllergyIntolerance?patient={id}
US Core AllergyIntolerance

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-allergyintolerance

Allergies and adverse reactions including clinical status, verification status, allergen substance (RxNorm / SNOMED CT / UNII), criticality, and reaction manifestations.

Search Parameters: patient, clinical-status, verification-status

GET /smart/CarePlan?patient={id}&category=assess-plan
US Core CarePlan

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan

Assessment and Plan of Treatment narrative, goals, planned interventions, and author references.

Search Parameters: patient, category, date, status

GET /smart/Condition?patient={id}
US Core Condition

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns

Diagnoses, problem list items, and health concerns encoded in ICD-10-CM and SNOMED CT.

Search Parameters: patient, category (problem-list-item, health-concern, encounter-diagnosis), clinical-status, code, onset-date

GET /smart/Device?patient={id}
US Core Implantable Device

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-implantable-device

Implantable medical devices and orthopedic hardware containing Unique Device Identifier (UDI) carrier details, expiration date, lot and serial numbers.

Search Parameters: patient, _id

GET /smart/DiagnosticReport?patient={id}&category=LAB
US Core DiagnosticReport

Profiles: us-core-diagnosticreport-lab & us-core-diagnosticreport-note

Laboratory reports, imaging / radiology reports, and clinical cardiology interpretations.

Search Parameters: patient, category, code, date, status

GET /smart/DocumentReference?patient={id}
US Core DocumentReference

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-documentreference

Clinical notes (Consultation Notes, Discharge Summaries, History & Physicals, Progress Notes, Procedure Notes) encoded with LOINC codes and base64 text or attached C-CDA XML.

Search Parameters: patient, category, type, date, status

GET /smart/Encounter?patient={id}
US Core Encounter

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter

Office visits, inpatient admissions, and outpatient surgical encounters with class, type, date period, and discharge disposition.

Search Parameters: patient, date, class, status

GET /smart/Immunization?patient={id}
US Core Immunization

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-immunization

Vaccination records using CDC CVX codes, administration date, lot number, dose, route, and completion status.

Search Parameters: patient, date, status

GET /smart/MedicationRequest?patient={id}
US Core MedicationRequest

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest

Prescriptions and medication orders coded with RxNorm, dosage instructions, quantities, refills, and status.

Search Parameters: patient, intent, status

GET /smart/Observation?patient={id}&category={category}
US Core Observations

Profiles: Vital Signs, Laboratory Results, Smoking Status, Clinical Tests, and Social Determinants of Health (SDOH).

Supported Observation Categories

  • vital-signs: Blood Pressure (systolic/diastolic), Heart Rate, Respiratory Rate, Body Temperature, Height, Weight, BMI, Pulse Oximetry
  • laboratory: Chemistry panels, CBC, urinalysis, orthopedic culture results
  • social-history: Tobacco smoking status (LOINC 72166-2), SDOH screenings
  • survey: Functional assessments, screening assessments

Search Parameters: patient, category, code, date, status

GET /smart/Procedure?patient={id}
US Core Procedure

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-procedure

Orthopedic surgeries, interventions, and procedures encoded in CPT, SNOMED CT, and ICD-10-PCS.

Search Parameters: patient, date, status, code

GET /smart/Provenance?target={resourceReference}
US Core Provenance

Profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-provenance

Audit and lifecycle provenance identifying the creating author, transmitting organization, recorded timestamp, and cryptographic signatures.

Search Parameters: target

FHIR Bulk Data Access (§ 170.315(g)(10))

Asynchronous Export

Under ONC § 170.315(g)(10), authorized clients can retrieve population-level clinical data asynchronously using the HL7 FHIR Bulk Data Access specification.

1. Initiate Export Request

Send an HTTP GET or POST request to the Group or Patient export endpoint with the mandatory Prefer: respond-async header:

Initiate Group Export (cURL)
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/Group/all-patients/\$export?_outputFormat=application/fhir%2Bndjson" \
  -H "Authorization: Bearer YOUR_SYSTEM_TOKEN" \
  -H "Accept: application/fhir+json" \
  -H "Prefer: respond-async"
HTTP 202 Accepted Response

The server immediately responds with 202 Accepted and includes a Content-Location header pointing to the export polling URL:

Content-Location: https://phoenixfhir-apim.azure-api.net/smart/_operations/export/7c9e6679-7425-40de-944b-e07fc1f90ae7

2. Poll Export Status

Periodically check the Content-Location URL until the export job completes:

Poll Status Request (cURL)
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/_operations/export/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_SYSTEM_TOKEN"

3. Download NDJSON File Manifest

When the job finishes, the server returns 200 OK with a complete JSON manifest containing direct download links for each resource type:

Completed Export Manifest (JSON)
{
  "transactionTime": "2026-10-02T14:30:00Z",
  "request": "https://phoenixfhir-apim.azure-api.net/smart/Group/all-patients/$export",
  "requiresAccessToken": true,
  "output": [
    { "type": "Patient", "url": "https://phoenixfhir-apim.azure-api.net/bulk-files/Patient.ndjson", "count": 105 },
    { "type": "Condition", "url": "https://phoenixfhir-apim.azure-api.net/bulk-files/Condition.ndjson", "count": 482 },
    { "type": "Observation", "url": "https://phoenixfhir-apim.azure-api.net/bulk-files/Observation.ndjson", "count": 2190 },
    { "type": "MedicationRequest", "url": "https://phoenixfhir-apim.azure-api.net/bulk-files/MedicationRequest.ndjson", "count": 315 },
    { "type": "Device", "url": "https://phoenixfhir-smart-auth.azurewebsites.net/api/mock-device-export", "count": 42 }
  ],
  "error": []
}

Application Access – Patient Selection API (§ 170.315(g)(7))

ONC § 170.315(g)(7) Certified

Under 45 CFR § 170.315(g)(7) (Application access – patient selection), the Phoenix Ortho EHR API provides authorized third-party applications with the functional capability to query demographic criteria to uniquely identify a patient, returning an identifier and/or security token that scopes subsequent data queries (such as C-CDA summary export under § 170.315(g)(9) or US Core FHIR resources under § 170.315(g)(10)).

Phoenix Ortho supports two compliant mechanisms for patient selection:

  • Mechanism 1: FHIR RESTful Demographic Search API – Direct HTTP query using demographic matching parameters (family name, given name, birthdate, gender, identifier).
  • Mechanism 2: SMART on FHIR Standalone Patient Launch – OAuth 2.0 authorization code flow with launch/patient scope, interactive or context-driven patient selection, and launch context token issuance.

Mechanism 1: FHIR RESTful Demographic Patient Search

Applications with patient read privileges can execute demographic queries against the Patient endpoint to match an individual patient record and obtain their unique resource identifier.

GET https://phoenixfhir-apim.azure-api.net/smart/Patient
FHIR R4 Bundle

Searches the clinical patient directory using US Core demographic parameters. All communication requires TLS 1.2 or 1.3 and a valid OAuth 2.0 Bearer token.

Query Parameters (API Syntax & Data Types)

Parameter Type Requirement Description & Example
family string Optional Patient last / family name (e.g. family=Jones or family=Shaw)
given string Optional Patient first / given name (e.g. given=Tyler or given=Amy)
birthdate date Optional Patient date of birth in ISO 8601 format YYYY-MM-DD (e.g. birthdate=1980-01-01)
gender token Optional Administrative gender code: male, female, other, or unknown
identifier token Optional Medical Record Number (MRN) or enterprise identifier (e.g. identifier=http://phoenixortho.net/mrn|PAT1000000013)
_id token Optional Logical FHIR resource ID (e.g. _id=phoenixortho.net-PAT1000000013)

Return Variables & Data Structure

Upon a successful match (HTTP 200), the API returns a FHIR R4 Bundle of type searchset. Each entry represents a matched patient conforming to the US Core Patient profile, exposing the internal unique identifier in resource.id:

Field Path Type Description
resourceType string Top-level bundle type: "Bundle"
type string Query response type: "searchset"
total integer Count of matched patient records
entry[].resource.id string Unique Patient Identifier – utilized by the client to execute all subsequent clinical data requests (e.g., C-CDA XML generation at /api/generate-ccda/{id} or US Core FHIR clinical observations)
entry[].resource.name HumanName[] Patient official and legal names (family, given, prefix, suffix)
entry[].resource.birthDate date Date of birth (YYYY-MM-DD)
entry[].resource.gender code Administrative gender (male | female | other | unknown)
entry[].resource.identifier Identifier[] Enterprise patient identifiers and clinic MRNs
entry[].resource.telecom ContactPoint[] Phone numbers and email contact information
entry[].resource.address Address[] Residential and postal address lines

Exceptions & Error Handling

HTTP Status Error Condition Response Body & Corrective Action
200 OK No Match Found Returns valid FHIR Bundle with "total": 0 and empty "entry": []. Client should refine demographic query parameters.
400 Bad Request Malformed Query Syntax Returns OperationOutcome detailing unsupported search parameters or invalid date/token encoding.
401 Unauthorized Missing or Expired Token Returns 401 with WWW-Authenticate: Bearer error="invalid_token". Client must obtain fresh access token from /auth/token.
403 Forbidden Insufficient Scopes Returns OperationOutcome indicating insufficient scope. Token must include patient/Patient.read, patient/Patient.rs, user/Patient.read, or system/Patient.read.
Demographic Search Request (cURL)
# Query patient by last name, first name, and birthdate
curl -X GET "https://phoenixfhir-apim.azure-api.net/smart/Patient?family=Jones&given=Tyler&birthdate=1980-01-01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"
Sample Patient Selection Response (FHIR JSON)
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://phoenixfhir-apim.azure-api.net/smart/Patient/phoenixortho.net-PAT1000000013",
      "resource": {
        "resourceType": "Patient",
        "id": "phoenixortho.net-PAT1000000013",
        "identifier": [
          {
            "system": "http://phoenixortho.net/mrn",
            "value": "PAT1000000013"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Jones",
            "given": ["Tyler"]
          }
        ],
        "gender": "male",
        "birthDate": "1980-01-01"
      }
    }
  ]
}

Mechanism 2: SMART on FHIR Patient Launch Context

In the SMART App Launch workflow, the client application requests the launch/patient scope during OAuth 2.0 authorization. The authorization server presents the user with an interactive patient selection dialog and returns the unique patient identifier directly in the token response payload.

POST https://phoenixfhir-apim.azure-api.net/auth/token
OAuth 2.0 Launch Context

Launch Flow Sequence

  1. Authorization Request: Client redirects user to https://phoenixfhir-apim.azure-api.net/auth/authorize requesting scope launch/patient openid fhirUser patient/*.read alongside PKCE code challenge.
  2. Patient Selection Prompt: During consent authorization, Phoenix Ortho renders the secure patient selection interface displaying active clinic patients.
  3. Authorization Code: Upon approval, an authorization code is issued to the client application's registered redirect URI.
  4. Token Exchange: Client POSTs the authorization code and PKCE code verifier to /auth/token.
  5. Patient Scoping Token: The token endpoint returns the access token along with the top-level patient launch context parameter.

Token Response Payload with Patient Context

Token Response with Launch Context (JSON)
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNtYXJ0LWF1dGgta2V5LTEi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "launch/patient openid fhirUser patient/Patient.read patient/Observation.read",
  "patient": "phoenixortho.net-PAT1000000013",
  "encounter": "EncounterA",
  "need_patient_banner": true,
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Subsequent Data Requests Using Selected Patient

External applications utilize the returned patient token parameter to execute targeted subsequent queries:

  • § 170.315(g)(9) C-CDA Export: GET https://phoenixfhir-sync-func.azurewebsites.net/api/generate-ccda/{patient}
  • § 170.315(g)(10) FHIR Clinical Resources: GET https://phoenixfhir-apim.azure-api.net/smart/Observation?patient={patient}
  • § 170.315(g)(10) Condition Problem List: GET https://phoenixfhir-apim.azure-api.net/smart/Condition?patient={patient}

Software Components & Technical Configuration

To successfully interact with the Phoenix Ortho Patient Selection API, external applications must implement the following technical configurations:

Component / Standard Requirement Implementation Specification
Transport Security Mandatory TLS 1.2 or TLS 1.3 encryption for all HTTP network connections
Data Interchange Mandatory HTTP/1.1 or HTTP/2 supporting JSON (application/json and application/fhir+json)
Authentication OAuth 2.0 + PKCE RFC 6749, RFC 7636 (PKCE with S256 code challenge method), and SMART App Launch IG v2.0
Client Registration Mandatory Applications must obtain a Client ID through the Phoenix Go administration portal before initiating authorization
Date / Time Format ISO 8601 All search parameters and response timestamps use ISO 8601 (e.g. YYYY-MM-DD)
💡 Public Accessibility Notice

This technical documentation is publicly accessible without any paywall, fee, registration, account creation, or "click-through" agreement, in full compliance with 45 CFR § 170.315(g)(7)(ii)(B).

C-CDA Generation & Export API (§ 170.315(g)(9))

Continuity of Care Document

Under ONC § 170.315(g)(9) (Application access – all data request), authorized applications can retrieve patient clinical summaries in HL7 Consolidated CDA (C-CDA R2.1) format containing all USCDI clinical domains.

GET https://phoenixfhir-sync-func.azurewebsites.net/api/generate-ccda/{scenario}
C-CDA XML

Generates an HL7 C-CDA R2.1 Continuity of Care Document conforming to LOINC 34133-9 (Summarization of Clinical Note) and ONC certification test criteria.

Preconfigured Certification Scenarios

Scenario Identifier Patient Demographics Key Clinical Sections & Data Included
scenario1 or alice-newman Alice Newman (Female, DOB 1970-05-01) Multi-condition problem list, Procedure Notes (28570-0), Referral Notes (11502-2), Medications, Allergies, Vital Signs, Results
scenario2 or george-alvarez George Alvarez (Male, DOB 1965-08-15) Cardiology consult, ECG observations, Lab panels, Social History, Plan of Treatment, Medical Equipment
scenario3 or happy-kid Happy Kid (Male, DOB 2014-03-20) Pediatric growth charts, CDC CVX Immunizations, Reason for Referral (22.1.3.1 & 19376.1.5.3.1.3.1), Goals
scenario4 or allison-foster Allison Foster (Female, DOB 2022-11-10) Infant / toddler developmental milestones, pediatric vital percentiles, Encounters, Care Team
Generate C-CDA Request (cURL)
# Generate live C-CDA for Scenario 1 (Alice Newman)
curl -X GET "https://phoenixfhir-sync-func.azurewebsites.net/api/generate-ccda/scenario1" \
  -H "Accept: application/xml"

Developer Sandbox & Test Patients

To accelerate testing and certification validation, the following test fixtures are pre-populated in the Phoenix sandbox:

Patient ID Patient Name Available Clinical Data
phoenixortho.net-PAT1000000013 Chuck Easttom Complete USCDI dataset (Demographics, Conditions, Observations, Allergies, Meds, Procedures, CarePlan)
scenario1 Alice Newman C-CDA Scenario 1 full clinical document test dataset
scenario2 George Alvarez C-CDA Scenario 2 cardiology and laboratory dataset
scenario3 Happy Kid C-CDA Scenario 3 pediatric growth and immunization dataset
scenario4 Allison Foster C-CDA Scenario 4 toddler milestones and vital sign dataset

Error Codes & Diagnostics

All errors returned by the Phoenix FHIR API use standard HTTP status codes and provide actionable diagnostic descriptions in a FHIR OperationOutcome resource payload.

Status Code Meaning Diagnostic Detail & Resolution
400 Bad Request Invalid Syntax or Parameter Check search parameter names, date prefixes (e.g. ge2020-01-01), or JSON structure
401 Unauthorized Missing or Expired Token Bearer token was omitted, has expired, or was revoked. Obtain a new token via /auth/token
403 Forbidden Insufficient Scope Access token does not include the required scope (e.g. attempting to read Observations with only patient/Patient.read)
404 Not Found Resource Not Found Resource ID or patient ID does not exist in the FHIR server
429 Too Many Requests Rate Limit Exceeded API rate limit reached (100 req/min). Retry request after interval indicated in Retry-After header

Terms of Service & Non-Discriminatory Access Policy

ONC § 170.315(g)(10) Compliant

1. Fair and Non-Discriminatory Access

Phoenix Ortho provides access to its certified FHIR API on terms that are objective, reasonable, transparent, and non-discriminatory to all health app developers, providers, and patients. No arbitrary fees or exclusivity arrangements are imposed for patient data access.

2. Developer Registration

Developers are required to register their application to obtain a Client ID. Registration requires identifying the developer entity, specifying application redirect URIs, and agreeing to standard acceptable use terms. Registration requests are processed automatically or within 3 business days.

3. Privacy, Security & Compliance

All communication requires TLS 1.2 or higher. Third-party applications accessing Protected Health Information (PHI) on behalf of covered entities must comply with applicable HIPAA and federal privacy regulations.

4. Rate Limits & Service Availability

To protect system stability, the API enforces a baseline burst protection rate limit of 100 requests per minute per client IP. Applications with large-scale or high-throughput integration requirements may contact our developer support team for elevated quota allocations.

5. Support & Contact

For technical inquiries, bug reports, or registration assistance, please contact our interoperability team at support@phoenixortho.net.