OnyxOS UM Vendor (UMV) API Documentation. Describes the CMS-0057-F regulatory background, the HL7 Da Vinci CRD, DTR, PAS and CDex Implementation Guides, and links to Capability Statements, Swagger documentation and Postman collections for UM Vendor integration with the Prior Authorization API.

Background

The OnyxOS EPA platform implements the Prior Authorization API required by CMS-0057-F using the HL7 Da Vinci Implementation Guides CRD, DTR, PAS and CDex, all at STU 2.1. This page gives payer and provider integration teams the regulatory background and a guide-by-guide description of what each IG does, who the actors are, and how the four fit into one end-to-end prior authorization flow.

Implementation Guide Version in use Role in the flow
CRD — Coverage Requirements Discovery STU 2.1 Tells the provider at the point of care whether prior auth is needed
DTR — Documentation Templates and Rules STU 2.1 Collects the documentation the payer requires, pre-filled from the EHR
PAS — Prior Authorization Support STU 2.1 Submits the request and returns the decision
CDex — Clinical Data Exchange STU 2.1 Lets the payer request additional clinical data or attachments

CMS-0057-F

CMS-0057-F, the CMS Interoperability and Prior Authorization Final Rule, was released on January 17, 2024, published in the Federal Register on February 8, 2024, and took effect on April 8, 2024. It requires impacted payers to expose a FHIR-based Prior Authorization API by January 1, 2027, and to meet new decision-timeframe, denial-reason and public-reporting obligations from January 1, 2026.

Impacted payers. Medicare Advantage organizations; state Medicaid and CHIP fee-for-service programs; Medicaid managed care plans (MCOs, PIHPs, PAHPs) and CHIP managed care entities; and Qualified Health Plan issuers on the Federally-facilitated Exchanges. Stand-alone dental plans and FF-SHOP-only issuers are excluded. The prior authorization provisions apply to items and services (including supplies and DME under the medical benefit) but not to drugs.

Operational requirements (from January 1, 2026). Payers must issue prior authorization decisions within 72 hours for expedited requests and 7 calendar days for standard requests (FFE QHP issuers are exempt from the timeframes), must give a specific reason with every denial, and must publicly post prior authorization metrics each year. Medicaid/CHIP managed care and QHP dates key off rating periods and plan years beginning on or after January 1, 2026.

API requirements (from January 1, 2027). Four FHIR APIs are required: the Prior Authorization API (the subject of this page), the Provider Access API, the Payer-to-Payer API, and an expanded Patient Access API that adds prior authorization data. The Prior Authorization API must let a provider find out whether prior authorization is required for an item or service, discover the documentation requirements, submit the request, and receive the decision, the status and the reason for any denial — which maps directly onto CRD, DTR and PAS.

Provider-side incentive. A new Electronic Prior Authorization measure is added to the MIPS Promoting Interoperability performance category and the Medicare Promoting Interoperability Program, beginning with the CY 2027 performance/reporting period.

Milestone Date Applies to
Rule published in the Federal Register 2024-02-08 All impacted payers
Rule effective 2024-04-08 All impacted payers
Decision timeframes, specific denial reasons, public PA metrics 2026-01-01 MA, Medicaid/CHIP FFS; managed care rating periods and QHP plan years on/after this date
Patient Access API usage metrics reported to CMS 2026-01-01 All impacted payers
Prior Authorization API, Provider Access API, Payer-to-Payer API, PA data in Patient Access API 2027-01-01 MA, Medicaid/CHIP FFS; managed care rating periods and QHP plan years on/after this date
MIPS Electronic Prior Authorization measure CY 2027 performance period MIPS clinicians, eligible hospitals, CAHs

State Medicaid and CHIP FFS programs may request an extension (potentially to 2028) or exemption, and FFE QHP issuers may seek an annual exception.

Accessing the APIs

UM Vendor APIs require each consuming application to be registered and authorized. Access is controlled through OAuth 2.0 using the client credentials grant type, enabling secure system-to-system integration.

Applications can be registered through the UM Vendor Portal. Utilization management vendors register a UM Vendor application, which is issued its own client credentials and scopes.

OnyxOS, the Interoperability Rule and FHIR Implementation Guides

OnyxOS has been designed to convert FHIR Implementation Guides into APIs. OnyxOS can ingest a capability statement and create the required APIs together with the relevant access controls.

In order to comply with CMS-0057-F we provide access to the following resources to support payers and providers who are integrating with the IGs identified in the previous section.

Implementation Guides

For implementers who are not familiar with HL7 FHIR Implementation Guides (IGs). An IG provides detailed information on data structures for resource profiles, operations and workflows. Each IG builds on the base FHIR Release 4 specification.

The relevant guides are:

Standards Foundation

The platform is built on HL7 FHIR R4 (4.0.1) and the four HL7 Da Vinci Implementation Guides above, all pinned to STU 2.1. CMS-0057-F names earlier versions of these guides as the recommended (not mandated) standards; STU 2.1 is the first release of each guide that incorporates post-rule connectathon and early-implementer feedback, and each has since been superseded by a 2.2.x release that is not yet adopted.

Standard Version in use Status / maturity Notes
CDS Hooks 2.0 STU Transport for CRD; the EHR calls the payer’s CDS service at workflow events
SMART App Launch 2.2 STU Authorization for DTR apps and provider-facing FHIR access
Da Vinci CRD 2.1.0 Trial use, FMM 3 Superseded by 2.2.1
Da Vinci DTR 2.1.0 Trial use, FMM 2 Superseded by 2.2.0
Da Vinci PAS 2.1.0 Trial use, FMM 3 Superseded by 2.2.1; X12 278 mapping licensed separately from X12
Da Vinci CDex 2.1.0 Trial use, FMM 2 Superseded by 2.2.x
Da Vinci HRex 1.1.0 STU Shared profiles (Task, Coverage, member matching) reused by CDex and PAS
Subscriptions R5 Backport 1.1 STU Cited by PAS for notifying the provider when a pended authorization is decided

Why Da Vinci. The HL7 Da Vinci Project is the payer–provider accelerator that produced these guides specifically for the value-based care and prior authorization use cases CMS-0057-F targets. Using them unchanged means provider EHRs that certify against the same guides can connect to the OnyxOS platform without bespoke integration.

HIPAA transaction interplay. The HIPAA standard for prior authorization transactions remains X12 278. PAS resolves this by allowing a FHIR-to-X12 conversion at an intermediary (or by the payer under enforcement discretion announced with the rule), so the provider-facing surface is FHIR end to end.

End-to-End Prior Authorization Workflow

The four guides chain into one flow that starts in the clinician’s EHR and ends with a decision from the payer. Each guide answers one question: CRD asks whether authorization is needed, DTR collects what the payer needs to decide, PAS carries the request and the decision, and CDex handles any follow-up request for clinical data.

Not every request walks all four steps. If CRD reports that no authorization is required, the flow ends at step 1. If the documentation gathered in DTR is sufficient, PAS returns a final decision and CDex is never invoked. CRD may also return a prior authorization directly during the hook interaction when payer rules allow, skipping DTR and PAS entirely.

Step Who initiates Transport Key FHIR artifact
CRD Provider EHR (automatically, on a workflow event) CDS Hooks 2.0 Card with the Coverage Information extension
DTR Provider EHR or SMART app, following the CRD card FHIR REST + SMART App Launch Questionnaire package, QuestionnaireResponse
PAS Provider EHR (or intermediary) FHIR operations $submit, $inquire Claim / ClaimResponse bundles
CDex Payer FHIR Task (request) and FHIR REST (response) Task, DocumentReference / attachment bundle

CRD — Coverage Requirements Discovery (STU 2.1)

CRD lets the payer tell the clinician, inside the EHR and at the moment an order or appointment is being created, whether the service is covered, whether prior authorization is required, and what documentation will be needed. It is the entry point of the CMS-0057 Prior Authorization API: the “is PA required?” question the rule obliges payers to answer. CRD STU 2.1 (v2.1.0) is trial-use at FHIR maturity level 3 and is built on CDS Hooks 2.0 and FHIR R4.

How it works. The EHR (CRD client) calls the payer’s CDS service (CRD server) when a hook fires. The payer evaluates the patient’s coverage and the proposed order and responds with CDS cards. Cards can carry plain guidance, links to a DTR questionnaire, or an instruction to update the order. The most important response is the Coverage Information extension placed on the order itself, which records whether PA is required, whether it was already satisfied, and any documentation needed; its satisfied-pa-id can be used as the X12 prior authorization number.

Actors

Actor Who Responsibility
CRD client Provider EHR, pharmacy, scheduling or registration system Fires hooks with prefetch context; renders cards; stores the Coverage Information extension on the order
CRD server OnyxOS EPA (payer CDS service) Evaluates coverage rules; returns cards and the Coverage Information extension; may return a PA directly where rules allow
ePA Coordinator Optional intermediary Orchestrates multi-system provider setups; described but not standardized in STU 2.1

Hooks supported. STU 2.1 covers the standard CDS Hooks for ordering and scheduling: order-select, order-sign, order-dispatch, appointment-book, encounter-start and encounter-discharge. The OnyxOS server responds to order-sign and order-select first, as these are where CMS-0057 requires PA determination; the others are prioritized by provider demand.

Key profiles. CRD constrains the resources the client must send and the server must understand: CRDServiceRequest, CRDMedicationRequest, CRDDeviceRequest, CRDNutritionOrder, CRDVisionPrescription, CRDAppointment (with and without an order), CRDCoverage, CRDPatient, CRDEncounter, CRDLocation, CRDOrganization, CRDDevice, CRDCommunicationRequest, plus CRDTaskDispatch and CRDTaskQuestionnaire for handing work to DTR. A CRDMetricData logical model defines the metrics both sides should log.

US Core alignment. CRD STU 2.1 ships three client capability sets, for US Core 3.1.1, 6.1.0 and 7.0.0, and one server capability set covering all three. The platform accepts any of the three from provider systems.

What changed from STU 2.0.1. The scope now includes a prior authorization returned during the CRD interaction, so a payer can approve on the spot without a PAS submission, and the guide was tightened from connectathon and early-implementer feedback. The full list is in the CRD change log.

DTR — Documentation Templates and Rules (STU 2.1)

DTR lets the payer publish its documentation requirements as FHIR Questionnaires with embedded CQL, so the provider’s system can pre-fill most answers from the patient record and show the clinician only what is still missing. It answers the CMS-0057 obligation to let providers discover and satisfy documentation requirements electronically. DTR STU 2.1 (v2.1.0) is trial-use at maturity level 2 on FHIR R4.

How it works. A CRD card (or a payer Task) points to a questionnaire. The DTR client calls the payer’s $questionnaire-package operation and receives a bundle with the Questionnaire, its CQL libraries and value sets. The client runs the CQL against EHR data via US Core (3.1.1, 6.1 or 7.0), renders the form with the pre-populated answers, and the clinician completes and signs it. The result is a QuestionnaireResponse that is stored in the EHR and attached to the PAS request (or sent via CDex when the payer asks later). Adaptive forms use $next-question, where the payer serves one question at a time based on prior answers, and ValueSet/$expand supports coded answers.

Actors

Actor Who Responsibility
Full DTR EHR Provider EHR with native form support Runs the whole DTR workflow internally; supports Questionnaire Package, ValueSet Expand and Next Question
Light DTR EHR SMART-enabled provider EHR Launches a SMART DTR app; exposes FHIR data and lets the app read and write QuestionnaireResponses
SMART DTR client Standalone or EHR-launched SMART app Fetches the package, executes CQL, renders the form, saves the QuestionnaireResponse
DTR payer service OnyxOS EPA Authors and serves questionnaires, CQL and value sets; supports the three operations server-side

Operations

Operation Direction Purpose
Questionnaire/$questionnaire-package Client → payer Returns the questionnaire(s), CQL libraries and value sets needed for a given order or coverage
Questionnaire/$next-question Client → payer Adaptive forms: payer returns the next question based on answers so far
ValueSet/$expand Client → payer Expands coded answer sets for form rendering

Key profiles. DTRQuestionnairePackageBundle, DTRStdQuestionnaire and DTRBaseQuestionnaire (static forms), DTRQuestionnaireAdapt and DTRQuestionnaireAdaptSearch (adaptive forms), DTRQuestionnaireResponse and DTRQuestionnaireResponseBundle, and capability statements for each actor (DTRPayerService, DTRSmartClient, LightDTREHR, FullDTREHR).

Design notes. Questionnaires are authored with CQL that references only US Core profiles so they run against any conformant EHR. Pre-populated answers are flagged as such in the QuestionnaireResponse, so reviewers can see what the clinician confirmed versus what was auto-filled. The change log from STU 2.0.1 is in the DTR version history.

PAS — Prior Authorization Support (STU 2.1)

PAS is the transaction that carries the prior authorization request from the provider to the payer and the decision back. It is the core of the CMS-0057 Prior Authorization API and the piece that must return approval, denial with a specific reason, or a pended status within the rule’s timeframes. PAS STU 2.1 (v2.1.0) is trial-use at maturity level 3 on FHIR R4.

How it works. The provider system assembles a PAS request bundle: a Claim resource (used here as the authorization request) with the patient, coverage, requesting and servicing providers, the ordered items, and supporting information such as the DTR QuestionnaireResponse. It posts the bundle to Claim/$submit. The payer responds synchronously with a ClaimResponse bundle whose outcome is approved, denied, partially approved, or pended. For pended requests the provider polls with Claim/$inquire or, where both sides support it, subscribes to be notified when the status changes. Updates to an open request are sent as a PASClaimUpdate.

Actors

Actor Who Responsibility
PAS EHR (client) Provider EHR or practice management system Builds and submits request bundles; handles responses, inquiries and update requests
PAS intermediary Clearinghouse or payer-contracted gateway Optional; converts FHIR to X12 278 and back where the payer’s adjudication system is X12-based
PAS payer (server) OnyxOS EPA Receives, validates and adjudicates requests; returns ClaimResponse bundles; serves inquiries and subscription notifications

Operations and bundles

Operation Request bundle Response bundle Purpose
Claim/$submit PASRequestBundle (PASClaim) PASResponseBundle (PASClaimResponse) Submit a new authorization request or an update (PASClaimUpdate)
Claim/$inquire PASInquiryRequestBundle (PASClaimInquiry) PASInquiryResponseBundle (PASClaimInquiryResponse) Query the status of a pended or previously submitted request
Subscription notification PASSubscription on a PASSubscriptionTopic PASSubscriptionNotification Payer notifies the provider when a pended decision is made (Subscriptions R5 Backport 1.1)

X12 278 relationship. PAS is designed so every element maps to the X12 278 request/response (and 275 for attachments). The FHIR-to-X12 mapping is published by X12 and requires an X12 license. The guide marks all mapped fields as Must Support and defers to the licensed X12 guides where it gives no direct guidance. Because HIPAA still names X12 278 as the standard transaction, the conversion happens at the intermediary or at the payer; the provider-facing API is FHIR only.

Decision semantics. A ClaimResponse carries an item-level adjudication with review action codes (approved, denied, pended, partial), the authorization number and validity period for approvals, and reason codes for denials. These are the fields the CMS-0057 “specific reason for denial” requirement and the public metrics draw on.

Attachments. Supporting documentation travels inline in the request bundle, or is requested afterwards by the payer through CDex (see the next section and the IG’s Using CDex Attachments with PAS guidance). PAS defines LOINC and PWK01 report-type value sets for attachment codes.

What changed from STU 2.0.1. STU 2.1 refines the intermediary and ePA Coordinator roles, aligns the bundles with the latest X12 mapping and tightens Must Support expectations; the full list is in the PAS change log.

CDex — Clinical Data Exchange (STU 2.1)

CDex is the general-purpose payer–provider data exchange guide. In the EPA platform it serves one job: when a prior authorization is pended because the reviewer needs more clinical evidence, CDex is how the payer asks for it and how the provider sends it back, tied to the authorization. CDex STU 2.1 (v2.1.0) is trial-use at maturity level 2 on FHIR R4 and reuses the Da Vinci HRex profiles.

Three exchange approaches. CDex defines three ways to move data; the platform uses the last two for prior authorization.

Approach Mechanism When it is used
Direct query Standard FHIR RESTful search against the provider’s FHIR server Not used for PA today; reserved for future Provider Access or utilization review use
Task-based request Payer POSTs a Task to the provider asking for specific data or a signed document; provider fulfils it asynchronously, with human review if needed Reviewer requests additional evidence for a pended authorization
Attachments Provider sends documentation to the payer’s $submit-attachment operation, identified by LOINC/X12 attachment codes or by a Questionnaire/QuestionnaireResponse Provider responds to a request, or sends unsolicited documentation, for a specific PA number

Actors

Actor Who Responsibility
Data consumer OnyxOS EPA (payer) Issues Task-based requests, receives attachments, links them to the authorization
Data source Provider EHR, HIM or practice management system Accepts Tasks, gathers or generates the data, returns it via attachment or Task output
Intermediary Optional May act on behalf of either party

How a pended authorization resolves. The payer creates a CDex Task on the provider’s endpoint referencing the PA (tracking identifier and the PAS Claim). The Task names what is needed either as a code (a LOINC document type), as a FHIR query, or as a DTR questionnaire to complete. The provider works the Task from its work queue, completes it, and sends the result to the payer’s $submit-attachment endpoint with the PA identifiers so the payer can match it automatically. The payer then re-adjudicates and the provider sees the new decision through PAS ($inquire or a subscription notification).

Signatures and provenance. CDex specifies when electronic or digital signatures are required on exchanged data, who signs, and how the enveloped signature is carried, so attachments used as evidence for an authorization can be verified. Requests also carry a purpose-of-use so the provider can apply its disclosure policies.

Relationship to PAS and DTR. PAS carries documentation inline at submission; CDex carries it afterwards. The IG’s “Using CDex Attachments with Da Vinci PAS” page sets out the overlap and the rules for choosing one or the other. DTR questionnaires can be requested through a CDex Task, so the same payer-authored forms are used whether documentation is gathered before or after submission. The change log from STU 2.0 is in the CDex version history.

Capability Statements

Server Capability Statements define the data profiles, operations, access methods and search operations that are supported by the server.

The Capability Statement can be referenced using the [base_url][/ig_name]/metadata endpoint.

Implementation Guide IG Short Name CapabilityStatement Link
Da Vinci CRD, DTR, PAS and CDex (Electronic Prior Authorization) epa https://api-dmdh-alpha.safhir.io/v1/api/epa/metadata

When working with different client instances of OnyxOS, the content of the capability statements will be the same with just the [base_url] value changing to point to a different environment.

Swagger Files

OnyxOS creates OpenAPI.json files, frequently referred to as swagger files from the Capability Statements provided. The swagger files enable developers to better understand the server interactions.

Swagger files are available for download using the same endpoint conventions as for capability statements. Therefore, if a Capability Statement is at:

  • [base_url][/ig_name]/metadata

The openapi.json file will be found at:

  • [base_url][/ig_name]/openapi.json
Implementation Guide IG Short Name Swagger Link
Da Vinci CRD, DTR, PAS and CDex (Electronic Prior Authorization) epa https://api-dmdh-alpha.safhir.io/v1/api/epa/openapi.json

Postman Collections

Postman is a popular API tool used by Developers. The Onyx Development team have provided a set of Postman collections to accelerate development of apps that use the FHIR APIs published by the SAFHIR platform.

The UM Vendor collection covers the subscription-notification request, which a UM Vendor uses to send a prior authorization status update (for example, a pended request needing follow-up) as a CommunicationRequest, with a happy-path example.

Implementation Guide IG Short Name Postman Collection Link
Da Vinci CRD, DTR, PAS and CDex (Electronic Prior Authorization) epa UM Vendor (UMV) Sandbox APIs

Postman Environments

Postman environments store the variables required to run the collections. Import the appropriate environment file alongside the collection and select it from the environment dropdown in Postman before making requests.

Implementation Guide IG Short Name Postman Environment Link
Da Vinci CRD, DTR, PAS and CDex (Electronic Prior Authorization) epa Electronic Prior Authorization (ePA) Sandbox Environment

Note: The client ID and client secret variables are intentionally left blank. Populate them with the credentials issued for your approved application in the Registration Portal.