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 |
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.
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) |
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
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
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.
Register a new client application with redirect URIs and JWKS public key endpoints.
{
"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 CompliantThe 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.
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 IDidentifier: Medical Record Number (MRN) or system IDname: Patient given or family namefamily: Patient last namegiven: Patient first namebirthdate: Patient birth date (supportseq,ge,le)gender: Administrative gender
{
"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"
}
]
}
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
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
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
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
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
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
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
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
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
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 Oximetrylaboratory: Chemistry panels, CBC, urinalysis, orthopedic culture resultssocial-history: Tobacco smoking status (LOINC 72166-2), SDOH screeningssurvey: Functional assessments, screening assessments
Search Parameters: patient, category, code, date, status
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
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 ExportUnder 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:
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"
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:
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:
{
"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) CertifiedUnder 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/patientscope, 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.
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. |
# 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"
{
"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.
Launch Flow Sequence
- Authorization Request: Client redirects user to
https://phoenixfhir-apim.azure-api.net/auth/authorizerequesting scopelaunch/patient openid fhirUser patient/*.readalongside PKCE code challenge. - Patient Selection Prompt: During consent authorization, Phoenix Ortho renders the secure patient selection interface displaying active clinic patients.
- Authorization Code: Upon approval, an authorization code is issued to the client application's registered redirect URI.
- Token Exchange: Client POSTs the authorization code and PKCE code verifier to
/auth/token. - Patient Scoping Token: The token endpoint returns the access token along with the top-level
patientlaunch context parameter.
Token Response Payload with Patient Context
{
"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) |
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 DocumentUnder 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.
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 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) Compliant1. 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.