Overview

The Prior Authorization FHIR API is a standards-based interoperability solution that enables healthcare providers, payers, Electronic Health Record (EHR) systems, and pharmacy applications to electronically submit, track, and manage prior authorization requests using the HL7® Fast Healthcare Interoperability Resources (FHIR®) framework.
The API streamlines the prior authorization process by providing real-time exchange of clinical, administrative, and coverage information, reducing manual workflows, minimizing delays, and improving transparency across the authorization lifecycle. It supports the electronic submission of authorization requests, retrieval of authorization status, exchange of supporting clinical documentation, and communication of approval, denial, or pending decisions.

Coverage Requirement Discovery (CRD)

CRD API tells a EHR right away if a treatment is covered by insurance and if approval is needed before doing it.
In simple words, it’s like a quick check that says “Can I go ahead, or do I need to do extra steps first?”. Follows https://hl7.org/fhir/us/davinci-pas/en/OperationDefinition-Claim-inquiry.html

Coverage Requirement Discovery (FHIR)

Determines whether prior authorization is required and retrieves coverage details for a requested service using FHIR-based CDS Hooks. The API evaluates member, provider, diagnosis, and service information to return real-time guidance, including prior authorization requirements, coverage insights, and links to initiate documentation workflows through DTR.

In Prior Auth Burden reduction initiative, the Coverage Requirement Check API enables seamless integration with the CMS Interoperability framework, supporting Prior Authorization workflows through CDS Hooks specifically order-sign hook. This API is designed to allow providers to determine prior auth requirements, retrieve coverage information, and initiate documentation workflows via DTR (Documentation Templates & Rules). This API follows the HL7 FHIR DaVinci CRD Implementation Guide standards.

This API facilitates:

• Coverage verification
• Prior Authorization (PA) requirement checks
• DTR link generation for questionnaire completion

Get available CDS Services (FHIR)

Retrieves the list of available CDS Services from the discovery endpoint following the CDS Hooks specification

Documentation Templates and Rules (DTR)

This API gives the EHR the exact forms/questions they need to fill for approval (based on the treatment and patient details).
In simple words, it’s like a guided form that asks the right questions step‑by‑step so all required info is collected correctly.

When creating orders, booking appointments, admitting patients, etc. there is often an expectation that certain types of documentation are captured that will subsequently be used for payer processing. This might be information needed for determining prior authorization (or whether prior authorization is even necessary), for inclusion as part of a claims submission, or even for retention as documentation of 'medical necessity' in the event of a future audit. There are clinical rules for what documentation is necessary and in what form it needs to exist. Failure to capture appropriate documentation or represent it in the correct manner can delay the processing of authorization requests and claims, result in denial of requests, or result in other penalties or hardships for both the provider and their patients.

As per Da Vinci Documentation Templates and Rules (DTR) implementation guide, Questionnaire operations are mechanism to express documentation requirements computably in a way that allows clinicians and other EHR users to navigate and quickly specify the needed information in a context-specific way.

DTR Capability Statement (FHIR)

The capability statement is a key part of the overall conformance framework in FHIR. It is used as a statement of the features of actual software, or of a set of rules for an application to provide. This statement connects to all the detailed statements of functionality, such as StructureDefinitions and ValueSets. This composite statement of application capability may be used for system compatibility testing, code generation, or as the basis for a conformance assessment.

CapabilityStatement outlining the server’s supported FHIR resources and operations for DaVinci DTR interactions, including questionnaire package and next question capabilities.

Get Questionnaire Package (FHIR)

Retrieves structured questionnaires and supporting artifacts required to capture the clinical information needed for prior authorization. The API returns a complete package—including questionnaire definitions, related responses, and dependencies—based on member coverage and context, enabling systems to guide providers through accurate and compliant data collection.

DTR Questionnaire Package Operation (API)
This operation returns one or more 'collection' Bundles each consisting of a single Questionnaire resource, one or more QuestionnaireResponse resources, as well as any dependency library and ValueSet instances needed to allow a renderer to fully render and otherwise process the Questionnaire.

The operation SHALL take as input the Coverage resource(s) identifying the member and the type(s) of Coverage for which additional information is needed and a CRD/PAS context ID.

If any of the explicitly requested questionnaires cannot be found, a warning SHALL be provided in the Outcome element of the outer Parameters resource. Similarly, if there is an issue understanding any of the orders or coverages and determining appropriate Questionnaires, a warning will be provided.

Get Next Question (FHIR)

Supports dynamic, step-by-step collection of documentation required for prior authorization using adaptive questionnaires. The API evaluates responses provided to date and returns the next relevant question(s), updating the questionnaire in real time until all required information is captured and the submission is complete.

DTR Next Question Operation (API)
The Next Question operation is used for adaptive questionnaires - forms where the next question (or set of questions) is based on previous answers. The result of this operation is to return an updated QuestionnaireResponse with a contained Questionnaire that includes the next question (or set of questions).

The client initiates and queries for the next question by including the answers to all required questions in the questionnaire to that point. The server updates the contained Questionnaire in the QuestionnaireResponse with the next question or set of questions and any needed instruction or score items. When the questionnaire is complete, the server updates the QuestionnaireResponse.status resource parameter from in-progress to completed. If completion of the questionnaire has exceeded any time limit, the server may return an OperationOutcome with an error.

Get Document Reference (FHIR)

Retrieves metadata and access details for clinical and administrative documents associated with a prior authorization workflow. The API returns DocumentReference resources that describe available documentation (such as clinical notes, questionnaires, or supporting files), enabling systems to locate, reference, and use the appropriate information required for authorization, claims processing, or audit purposes.

DTR Document Reference Operation (API)
The Document Reference API is used to represent metadata (in the form of DocumentReference resource) about a clinical document or other healthcare-related content. It does not store the actual document content (though it can link to it), but rather describes the document and how to access it.

This API is used to index a document, clinical note, questionnaire note, answer note and other binary objects such as a photo, video, or audio recording, including those resulting from diagnostic or care provision procedures, to make them available to a healthcare system.

Prior Authorization Support (PAS)

Prior Authorization Support (PAS) is a healthcare authorization solution that streamlines the submission, review, tracking, and management of prior authorization requests between healthcare providers and payers. It helps ensure that requested treatments, medications, procedures, or services meet clinical and coverage requirements before approval is granted.

PAS supports the end-to-end prior authorization lifecycle, including determining authorization requirements, collecting required clinical documentation, electronically submitting requests, monitoring case status, and managing approval or denial outcomes.

PAS Capability Statement (FHIR)

Shows how you can use PAS APIs and what features are supported before you start submitting requests.

Case Search (FHIR)

Enables retrieval of previously submitted prior authorization cases using a FHIR-based inquiry aligned with X12 278 standards. The API returns case details based on a reference number and only when the requesting provider is associated with the case (e.g., submitting, ordering, admitting, or servicing provider).

This operation enables a query for a previously submitted Pre-Authorization using the FHIR $inquire operation, aligned with X12 278 Inquiry standards.

Input

• A single FHIR Bundle containing:
  • A PASClaimInquiry resource
  • All related referenced resources (e.g., Organization, Practitioner)

Output

• A Bundle containing:
  • Zero or more PASClaimInquiryResponse resources
  • Or an OperationOutcome resource if no match or error occurs

How It Works

• The system searches for a case using the Claim/Case Reference Number
• Case details are returned only if the care provider is listed as:
  • Submitting/requesting provider
  • Ordering provider
  • Admitting/attending provider
  • Servicing provider

Standard Case/Submit (FHIR)

Enables electronic submission of prior authorization requests using the FHIR Prior Authorization Support (PAS) $submit operation, aligned with CMS Burden Reduction requirements. The API accepts a structured request with supporting documentation, validates it against FHIR and payer-specific rules, and returns adjudication results including status (approved, pended, or denied) along with any errors or informational messages.

The $submit operation is defined in the HL7 FHIR Prior Authorization Support (PAS) Implementation Guide. It allows providers to electronically submit prior authorization requests to payers in a standardised format, meeting CMS Burden Reduction requirements.

This API:

• Accepts a FHIR Bundle containing the prior authorization request and supporting documentation.
• Validates the request for compliance and business rules.
• Returns adjudication results and any error or informational messages.

What Does $submit Perform?

• Receives a prior authorization request from the provider.
• Validates:
  • FHIR structure and required elements.
  • Payer-specific business rules.
• Processes the request and returns:
  • ClaimResponse: Indicates status (approved, pended, denied).
  • OperationOutcome: Provides errors, warnings, or guidance (optional).

Submit Attachment -CDEX (FHIR)

Enables submission of supporting clinical and administrative documentation to an existing prior authorization request using the FHIR $submit-attachment operation. The API accepts structured attachment data (e.g., PDF, image, or document) and associates it to the correct authorization case, validating required identifiers and linkage details. A response is returned confirming successful processing and association, along with tracking metadata and any informational or error messages.

This API enables the operation to submit solicited and unsolicited attachments or additional clinical/administrative information to a prior authorization request. The $submit-attachment operation accepts clinical and administrative attachments along with the information required to associate them with the correct prior authorization and returns an appropriate HTTP response.

Accepts a FHIR Parameters payload that carries a DocumentReference containing an Attachment (e.g., DOC, PDF, image). The attachment is associated with the business object identified by the reference-srn header.

Required Fields

• TrackingId – Identifier (system, value)
• AttachTo – Must be preauthorization
• MemberId – Identifier for the member
• Attachment – part → DocumentReference → Attachment

Operation Definition for Capability Statement (FHIR)

The OperationDefinition resource provides a formal, computable definition of a FHIR operation or named query, enabling systems to understand how specific operations (such as submit or inquire) are invoked and processed.

It serves two primary purposes: to support automatic system compatibility determination by clearly defining supported operations and their behavior, and to enable dynamic generation of user interfaces or forms required to execute those operations.

The OperationDefinition endpoint allows clients to discover and retrieve metadata about supported operations, including their parameters, inputs, and expected outputs, enabling standardized and interoperable system interactions.

Test API

1. Use token generated using client ID and secret key for sandbox or production.
2. Download API specs from overview page - every API overview section provides links to download the file in a JSON format, which generates our documentation for developers to use.
3. Hit API endpoint through the following options:
   -Use Try It page to request complete API response or customize response for
   Sandbox API endpoint only.

OR
-Use Postman to request complete API response or customize response for Sandbox and
Production API endpoint.

NOTE: Do not submit PHI or PII data in the Try It page.

Sandbox use for mock data testing

1. The customer will retain the ability to query mock responses from a sandbox environment by using an optional request header called “environment”. By placing the value “sandbox" in the optional header, the request return mock responses.
   NOTE: Do not submit PHI or PII data in the TRY IT page.
2. For live data testing pass header parameter x-prod-data-enabled with a value "True"

End-to-End API invoking Workflow Pointers

• Capability APIs give details like:
  - “what this system can do” before even start using it
  - Which APIs are available
  - What actions you can perform (submit, check status, attach docs, etc.)
  -What formats and rules are supported
• DTR Capability API tells your system what form-related features (questions, flows, formats) are supported before you start using DTR APIs.
• PAS Capability API shows how you can use PAS APIs and what features are supported before you start submitting requests.
• Operation Definition API explains how a specific API (PAS/DTR ) works — what input to send and what response to expect.
  NOTE: Input to Operation Definition API comes from the response of PAS/DTR Capability APIs.
• Discovery API tells what checks and recommendations are available for CRD request.

CRD → checks if approval is needed → DTR → collects required info via forms → PAS → submits request for decision → CDEX → sends any additional documents if needed.

---

Provider subscribes to Prior Auth API on AI marketplace: Provider receives client ID and secret. Use the client ID and secret for Token generation which then must be used to invoke all API endpoints Prior Auth API bundle includes listed below.

Base URLs and Path Params

Integration workflow table

API Endpoint

Notes:
DO NOT perform load testing or production data testing in the sandbox environment. Please use the sandbox ONLY to view sample API responses to HTTP requests using our predefined values and to familiarize yourself with our APIs.

To perform load testing and production data testing, we recommend using our APIs in the production environment.

API health check

The health check endpoint checks the operating status of our API. It is a ping for the API entry point to ensure the entry points are accessible. This is the first thing you can do if something goes wrong.

• To run the health check of an Optum Real API - the Real Pre Service Eligibility API, go to
  Healthcheck If the API engine is working correctly and if the entry points are accessible, the API operating status response shows "OK."

NOTE If you receive a response other than 200 OK, the health check failed.
Please submit a service ticket with Optum.