CareFirst BlueCross BlueShield makes a set of HL7® FHIR®-based APIs available on the API Marketplace to support compliance with two CMS final rules:

• CMS-9115-F (CMS Interoperability and Patient Access final rule, 2020) introduced the Patient Access API, Provider Directory API, and Payer-to-Payer API.
• CMS-0057-F (CMS Interoperability and Prior Authorization final rule, finalized January 2024) adds the Provider Access API and Prior Authorization API, and expands the Patient Access and Payer-to-Payer APIs to include certain prior authorization information.

Compliance dates vary by API and payer type. Operational provisions (such as prior authorization decision timeframes and public metric reporting) generally began January 1, 2026; API build-out requirements generally take effect January 1, 2027. Developers should confirm specific compliance dates for the line of business they are integrating with against the authoritative CMS-0057-F final rule.

API Availability Matrix

Legend

• Yes — The API is available for this line of business / plan.
• NA — The API is not applicable, or not in scope, for this line of business / plan.

Footnotes

• * — Availability is limited to CMS-9115-F mandate requirements only; the CMS-0057-F enhancements (e.g., expanded prior authorization data) do not apply to this plan.
• ** — For former CHPDC (DC Medicaid) members, data — including clinical data — remains available through the Payer-to-Payer API until September 30, 2029.

Who Can Access These APIs

• The Patient Access API and Payer-to-Payer API require member (or personal representative) authorization and are intended for authorized third-party applications and payer organizations, respectively.
• The Provider Directory API is publicly accessible and does not require member authorization.
• The Provider Access API is intended for contracted CareFirst providers, health systems, EHR vendors, and other authorized healthcare technology partners.
• The Prior Authorization API supports electronic prior authorization workflows for contracted providers and their technology partners.

Application approval, registration, and credentialing follow the standard API Marketplace developer workflow. To get started, see Register as a Developer, Register Your Application, and Invoking APIs Using Authorization Code Grant Type. API base URLs, endpoints, and paths are listed in Base URL under Additional Information.

Related Information

• API Marketplace FAQs
• BCBSA Interoperability Mandate (IPP 1.03) API Availability page — for Provider Access and Prior Authorization availability across additional CareFirst lines of business not covered by the CMS mandate

---

In addition to the federal CMS interoperability mandates, CareFirst participates in the Blue Cross Blue Shield Association's Inter-Plan Programs (IPP) framework, which governs how Blue plans exchange data for members who receive care outside their home plan's service area (BlueCard members). Published, publicly available detail specific to "IPP Policy 1.03" was not available during the drafting of this page; the summary below reflects general, publicly reported information about the related BCBSA Interoperability Hub initiative and should be confirmed against the authoritative BCBSA policy source before publication.

Based on publicly available third-party reporting (not an official BCBSA policy document), the BCBSA Interoperability Hub is described as a shared platform that lets Home and Host Blue plans securely exchange member and prior authorization data for BlueCard members using FHIR-based standards. Reported timelines indicate Blue plans were expected to connect to the Hub by March 31, 2026, and to support data exchange across all lines of business by January 1, 2027. These details are third-party reported and must be confirmed against CareFirst's internal compliance source before publication.

Under this mandate, CareFirst makes the Provider Access API and Prior Authorization API available across a broader set of lines of business than the CMS mandate covers — including commercial, Federal Employee Program (FEP), and additional exchange lines of business. The Patient Access, Provider Directory, and Payer-to-Payer APIs are not part of this mandate; their availability is governed separately under the CMS Interoperability mandate (see the related CMS Interoperability API Availability page).

API Availability Matrix

Legend

• Yes — The API is available for this line of business / plan.
• NA — The API is not applicable, or not in scope, for this line of business / plan.

Footnotes

• * — CFA is not in scope for the January 1, 2027 go-live.

To get started, see Register as a Developer, Register Your Application, and Invoking APIs Using Authorization Code Grant Type. API base URLs, endpoints, and paths are listed in Base URL under Additional Information.

Related Information

• CMS Interoperability Mandate (CMS-9115-F & CMS-0057-F) API Availability page — for Patient Access, Provider Directory, and Payer-to-Payer API availability
• API Marketplace FAQs

---

1. Overview

The CareFirst Coverage Requirements Discovery (CRD) API is a synchronous CDS Hooks service that enables an Electronic Health Record (EHR) or authorized third-party application to discover coverage and prior authorization requirements at the point of care. The API uses FHIR R4 resources supplied in CDS Hooks context and prefetch data and follows the CareFirst implementation of the Da Vinci CRD workflow.

The business objective is to provide timely guidance before a service is delivered by answering the following questions:

• Is the requested service covered for the identified member?
• Is prior authorization required?
• Is additional documentation required?
• Is there an instruction, external reference, or system action that the provider should apply?
• Should the request be processed by CareFirst or routed through an applicable inter-plan workflow?

The API validates the hook request and included FHIR resources, resolves the member from Coverage, performs applicable plan routing and rules evaluation, and returns CDS Hooks cards and/or system actions.

A CRD response provides coverage and utilization-management guidance. It is not a prior authorization approval and is not a guarantee of payment. When prior authorization is required, the consumer must continue the applicable documentation and authorization workflow.

2. API Profile

Hook classification

3 Prerequisites

Before calling the API, a third-party consumer must complete the following prerequisites.

1. Application onboarding
   • Register the organization and application through the CareFirst API onboarding process.
   • Obtain CRD product entitlement for each required environment.
   • Complete applicable security, privacy, legal, and connectivity reviews.
2. Authentication and connectivity
   • Obtain the OAuth client identifier, client secret or approved equivalent, token endpoint, API access key, and assigned scopes.
   • Configure HTTPS and CareFirst-approved TLS settings.
   • Store credentials securely. Do not place credentials in source code, URLs, logs, or user-visible messages.
   • Use environment-specific URLs and credentials.
3. CDS Hooks implementation and fixed CareFirst CRD prefetch contract
   • Generate a unique UUID for every hookInstance.
   • Select the CareFirst-published CRD service identifier and call POST /cds-services/{service-id}.
   • Construct the hook-specific context required by the applicable CDS Hooks specification.
   • Implement the fixed CareFirst CRD prefetch contract. Providers must include the required FHIR resources listed below with each applicable hook invocation. Only resource names are listed here; prefetch queries remain defined by the CareFirst service contract.
     • appointment-book: Patient, Encounter, Coverage, ServiceRequest, PractitionerRole, Practitioner, Organization, Location.
     • encounter-start: Patient, Encounter, Coverage, PractitionerRole, Practitioner, Organization, Location.
     • encounter-discharge: Patient, Encounter, Coverage, PractitionerRole, Practitioner, Organization, Location.
     • order-dispatch: Patient, Encounter, Coverage, CommunicationRequest, DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription, Device, Medication, PractitionerRole, Practitioner, Organization, Location.
     • order-select: Patient, Encounter, Coverage, Device, Medication, PractitionerRole, Practitioner, Organization, Location.
     • order-sign: Patient, Encounter, Coverage, Device, Medication, PractitionerRole, Practitioner, Organization, Location.
   • Provider systems are responsible for populating and sending the required prefetch resources. CareFirst does not currently support payer-initiated queries that retrieve these resources directly from the provider EHR.
   • Preserve valid references among Patient, Coverage, Encounter, orders, practitioners, organizations, locations, devices, and medications.
   • Use the exact prefetch keys and queries published in the CareFirst service contract. Resource names in this document do not replace the executable service definition.
4. Member and Coverage data
   • Include an active Coverage resource.
   • Populate Coverage.subscriberId whenever available.
   • If Coverage.subscriberId is unavailable, include a Coverage identifier with type code MB and the member identifier as its value.
   • Ensure that Coverage beneficiary/subject references are consistent with the Patient in the request.
5. Clinical and order data
   • Use ServiceRequest or DeviceRequest for full CRD order evaluation.
   • Include the orders applicable to the current hook invocation.
   • Use CareFirst-supported CPT, HCPCS, revenue, and ICD-10 coding as applicable.
   • Include requesting and servicing practitioner data and related organizations and locations when required.
   • When multiple diagnoses are supplied, identify the principal diagnosis consistently with the CareFirst contract.
6. Operations and security
   • Supply required correlation headers, such as x-clientrefid, x-correlationid, and x-cf-guid, when specified by the environment contract.
   • Do not include PHI in URLs, correlation identifiers, telemetry, or unapproved logs.
   • Implement timeout handling, safe retry controls, monitoring, and audit logging.
   • Validate the request locally before sending it.

Illustrative request

{
  "hook": "order-sign",
  "hookInstance": "8aff3f80-5b16-4ec5-b5a0-fb61e3c87b21",
  "context": {
    "userId": "PractitionerRole/123",
    "patientId": "Patient/456",
    "encounterId": "Encounter/789",
    "draftOrders": {
      "resourceType": "Bundle",
      "type": "collection",
      "entry": [
        {
          "resource": {
            "resourceType": "ServiceRequest",
            "id": "sr-1001",
            "status": "draft",
            "intent": "order",
            "subject": { "reference": "Patient/456" }
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": { "resourceType": "Patient", "id": "456" },
    "encounter": { "resourceType": "Encounter", "id": "789", "status": "in-progress" },
    "coverage": {
      "resourceType": "Coverage",
      "id": "cov-1",
      "status": "active",
      "subscriberId": "ABC123456789",
      "beneficiary": { "reference": "Patient/456" }
    }
  }
}

This sample is abbreviated. It does not show every prefetch resource required for order-sign. Consumers must send all resources required by the fixed CareFirst prefetch contract and use the exact published prefetch property names.

4 Supported Capabilities

• Invoke CRD through POST /cds-services/{service-id}.
• Discover CDS service definitions through GET /cds-services, when enabled.
• Check service availability through GET /status, when enabled.
• Classify supported, recognized-but-not-evaluated, and unrecognized hooks.
• Evaluate qualifying ServiceRequest and DeviceRequest resources.
• Resolve the member from Coverage.subscriberId, with fallback to a Coverage identifier with type code MB.
• Determine coverage and whether prior authorization is required.
• Indicate when additional documentation is required, when available from the applicable rules response.
• Return CDS Hooks cards with summary, detail, indicator, source, and links when applicable.
• Return supported system actions containing coverage-information data for eligible requests.
• Route applicable inter-plan requests according to CareFirst plan-routing rules.
• Support transaction tracing with approved correlation identifiers.

HTTP invocation

POST /cds-services/{service-id} HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
x-clientrefid: {caller-reference}
x-correlationid: {correlation-id}
Content-Type: application/json
Accept: application/json

Illustrative response

{
  "cards": [
    {
      "uuid": "2e3eb24d-b59d-458f-b634-d3627b57a17f",
      "summary": "Coverage requirements are available",
      "detail": "Review the coverage and prior authorization information for the requested service.",
      "indicator": "info",
      "source": {
        "label": "CareFirst Coverage Requirements Discovery"
      }
    }
  ],
  "systemActions": []
}

The exact card, extension, and system-action structure is defined by the release-specific CareFirst contract. An HTTP 200 response is not an authorization approval.

5 Limitations

• Full order evaluation is limited to supported ServiceRequest and DeviceRequest workflows.
• Recognized hooks that are not evaluated may return informational cards without system actions.
• Provider systems must supply the complete fixed prefetch data. CareFirst does not currently query the provider EHR to retrieve missing prefetch resources.
• Unsupported procedure or diagnosis coding systems may produce an unprocessable-request response.
• Missing required clinical, member, practitioner, or servicing information may prevent evaluation.
• A CRD result reflects information available at the time of the request. Coverage, eligibility, benefits, and rules may subsequently change.
• A covered result does not guarantee payment.
• A prior-authorization-not-required result does not replace eligibility, medical necessity, benefit, or claims requirements.
• A prior-authorization-required result does not create or submit an authorization request.
• Inter-plan processing depends on the availability of applicable external routing services.
• Endpoint URLs, scopes, request-size limits, rate limits, retry intervals, and service levels are environment and release specific.
• Consumers must not expose internal routing details, backend error codes, credentials, or sensitive member information to end users.

6 Typical Interaction

1. A provider starts a supported clinical workflow.
2. The EHR selects the applicable CareFirst CRD service.
3. The EHR constructs the hook-specific context.
4. The provider system collects and populates every resource required by the fixed prefetch contract for that hook.
5. The EHR sends an authenticated request with a unique hookInstance and required correlation identifiers.
6. CareFirst validates authentication, JSON syntax, hook data, prefetch completeness, FHIR resources, references, and coding.
7. CareFirst resolves the member from Coverage.
8. CareFirst applies applicable plan-routing logic.
9. For an eligible request, CareFirst evaluates coverage and prior authorization rules.
10. CareFirst returns CDS Hooks cards and/or system actions.
11. The EHR displays the guidance and applies supported actions within the provider workflow.
12. If further documentation or prior authorization is required, the provider continues the appropriate downstream workflow.

Provider workflow
  -> Build hook context
  -> Populate fixed CareFirst prefetch resources
  -> Authenticate and invoke CRD
  -> Validate hook, FHIR data, and references
  -> Resolve member and plan routing
  -> Evaluate coverage and PA requirements
  -> Return CDS Hooks cards/system actions
  -> Display guidance in the EHR

Consumers must evaluate the HTTP status, cards, and system actions separately. They must not interpret HTTP 200 alone as a positive coverage or authorization result.

7 Core Schema Elements

Member identifier resolution

1. Use Coverage.subscriberId when present.
2. Otherwise, use Coverage.identifier[type.coding.code="MB"].value.
3. If the member identifier cannot be resolved, return the applicable informational or error response and stop downstream evaluation.

Prefetch interpretation

• The prefetch list varies by hook and must be implemented exactly as specified in Section 3.
• The presence of a resource type in the list means the provider must support supplying that resource under the fixed contract for the applicable hook.
• The CareFirst service contract defines the actual prefetch keys, FHIR queries, cardinalities, profiles, and handling of empty results.
• References among resources must resolve within the submitted data as required by the contract.

8 Validation and Error Handling

Illustrative OperationOutcome

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "details": {
        "text": "A resource required by the CareFirst CRD prefetch contract is missing."
      }
    }
  ]
}

Consumer error-handling requirements

• Log the HTTP status, request timestamp, environment, service identifier, hookInstance, and approved correlation identifiers.
• Do not log access tokens, secrets, full member identifiers, clinical payloads, or PHI unless explicitly permitted by CareFirst controls.
• Do not retry validation failures without correcting the request.
• Retry transient failures only when allowed by the CareFirst contract, using bounded backoff.
• Do not assume CareFirst will retrieve omitted prefetch resources from the provider EHR.
• Do not interpret every HTTP 200 response as a successful coverage determination. Inspect the cards and system actions.
• When the result is unavailable or ambiguous, do not represent the service as authorized or guaranteed to be covered.

1. Overview

The CareFirst Documentation Templates and Rules (DTR) API enables an Electronic Health Record (EHR), provider application, or other authorized third-party client to retrieve and complete the clinical questionnaires needed to support prior authorization and related documentation workflows.

The API provides three complementary FHIR operations:

• Questionnaire/$questionnaire-package retrieves the applicable questionnaire package and supporting artifacts.
• Questionnaire/$next-question advances an adaptive questionnaire after the provider submits answers.
• ValueSet/$expand resolves coded answer choices referenced by a questionnaire during an applicable BCBSA adaptive session.
• Questionnaire/$log-questionnaire-errors allows an EHR DTR client to report questionnaire, rendering, CQL, terminology, or submission errors associated with a DTR session.

The business objective is to present the correct payer documentation requirements within the provider workflow, reduce manual form discovery, collect structured clinical information, and return consistent FHIR R4 artifacts even when CareFirst must route the request to different downstream systems.

CareFirst acts as the orchestration layer. For a questionnaire-package request, it validates the FHIR request, identifies the member, determines applicable plan routing, resolves the questionnaire vendor, and returns a questionnaire package. For an adaptive questionnaire, it retains session-routing context so subsequent next-question calls can be sent to the correct vendor. When a BCBSA questionnaire references external coded answer options, the expand operation proxies the terminology request to the BCBSA Interoperability Hub. When an EHR reports questionnaire errors, CareFirst uses the Questionnaire canonical URL to resolve the originating session. BCBSA session errors are forwarded to the BCBSA Interoperability Hub, while unresolved and non-BCBSA errors are recorded in the CareFirst audit trail.

The DTR API does not submit a prior authorization request and does not make a final authorization decision. Completing a questionnaire creates documentation that may be used in a later prior authorization workflow.

This document is a consumer-facing integration guide. The published CareFirst API contract, FHIR profiles, environment onboarding material, and operation definitions remain authoritative for base URLs, scopes, headers, canonical URLs, profiles, cardinalities, and release-specific behavior.

2. API Profile

Operation summary

3 Prerequisites

Before integrating with the DTR API, a third-party consumer must complete the following prerequisites.

1. Application onboarding
   • Register the organization and application through the CareFirst API onboarding process.
   • Obtain DTR product entitlement for each required environment.
   • Complete applicable security, privacy, legal, and connectivity reviews.
   • Obtain the environment-specific base URL, token endpoint, scopes, API access key, and support contacts.
2. Authentication and transport
   • Implement OAuth 2.0 Client Credentials using the credentials issued by CareFirst.
   • Send the bearer token and any required API access key on every request.
   • Use HTTPS and the CareFirst-approved TLS configuration.
   • Protect secrets in an approved secret store. Do not place tokens or credentials in URLs, application logs, or user-facing messages.
3. FHIR R4 and DTR support
   • Send and receive application/fhir+json.
   • Support FHIR Parameters, Bundle, Questionnaire, QuestionnaireResponse, Coverage, ServiceRequest, DeviceRequest, Patient, Encounter, Condition, Practitioner, PractitionerRole, Organization, Location, Library, and ValueSet resources as applicable.
   • Preserve resource identifiers, canonical references, and references among submitted resources.
   • Use the exact CareFirst-published profiles, extensions, value sets, operation definitions, and parameter names.
   • Be able to render both standard and adaptive Questionnaires and collect answers in a QuestionnaireResponse.
   • Be able to retain the Questionnaire canonical URL and identifier returned by CareFirst and send the correct reference in later calls.
4. Questionnaire-package request preparation
   • Construct a FHIR Parameters resource for POST /Questionnaire/$questionnaire-package.
   • For an order-based request, include the required coverage parameter and at least one supported order parameter.
   • Ensure the Coverage and order references resolve to resources included as required by the CareFirst contract.
   • Use ServiceRequest or DeviceRequest for supported order-based processing.
   • Include applicable referenced clinical context, such as Patient, Encounter, Condition, practitioner, organization, and location information.
   • Populate procedure or service codes using CareFirst-supported CPT, HCPCS, or revenue coding.
   • Populate diagnosis using supported ICD-10 coding when required.
   • Include requesting practitioner, servicing practitioner, and place-of-service information when required for rules evaluation.
   • If the CareFirst contract permits a context-based request, include the context value exactly as issued by the originating workflow. Context-based requests may follow different validation and routing rules from order-based requests.
5. Member identification
   • Include a resolvable Coverage resource for order-based requests.
   • Populate Coverage.subscriberId whenever available.
   • If Coverage.subscriberId is unavailable, supply a Coverage identifier with type code MB and the member identifier as its value.
   • Ensure Coverage beneficiary and Patient references are consistent.
6. Adaptive questionnaire support
   • Start the session with $questionnaire-package before calling $next-question.
   • Retain the Questionnaire identifier and canonical reference returned in the package.
   • Send a QuestionnaireResponse with status set to in-progress while requesting additional adaptive questions.
   • Populate QuestionnaireResponse.questionnaire with the originating Questionnaire canonical reference or identifier required by the CareFirst contract.
   • Treat the adaptive session as time limited. If session state expires, restart with a new questionnaire-package request.
   • Do not change a returned adaptive endpoint, questionnaire identifier, session UUID, or canonical URL.
7. ValueSet expansion support
   • Call the terminology URL returned or referenced by the applicable questionnaire package.
   • Preserve the UUID path segment exactly as returned for the BCBSA session.
   • Send the supported FHIR $expand query parameters without changing their meaning.
   • Use $expand only for questionnaires whose terminology endpoint directs the client to this CareFirst proxy. Other vendor questionnaires may provide answer choices inline or use a different terminology mechanism.
8. Questionnaire error-reporting support
   • Implement POST /Questionnaire/$log-questionnaire-errors using the DTR Log Questionnaire Errors Input Parameters profile: http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-log-errors-input-parameters.
   • Send exactly one Questionnaire parameter with the canonical URL of the Questionnaire that generated the error. A version-specific canonical URL should be used when available.
   • Send exactly one OperationOutcome parameter containing a valid FHIR R4 OperationOutcome that describes the questionnaire, CQL, rendering, terminology, or QuestionnaireResponse error.
   • Use the exact Questionnaire canonical URL returned by $questionnaire-package. CareFirst uses this value as the session-routing cache key.
   • Include useful diagnostic context in the OperationOutcome, such as the DTR application identity and version, date and time with timezone offset, provider endpoint, error location, and safe diagnostics.
   • Do not include PHI or information retrieved from provider FHIR APIs in the error-reporting OperationOutcome.
   • Treat error reporting as best effort. An HTTP 200 acknowledgement indicates that CareFirst handled the report, but does not necessarily mean it was forwarded to a downstream vendor.
9. Operational readiness
   • Generate and propagate the correlation identifiers required by the environment contract.
   • Implement safe timeout and retry handling.
   • Do not place PHI in URLs, correlation identifiers, telemetry, or unapproved logs.
   • Validate FHIR requests locally before sending them.
   • Treat a FHIR OperationOutcome as an unsuccessful business result even when an operation-specific implementation returns HTTP 200.

Illustrative questionnaire-package request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "coverage",
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-1",
        "status": "active",
        "subscriberId": "ABC123456789",
        "beneficiary": {
          "reference": "Patient/patient-1"
        }
      }
    },
    {
      "name": "order",
      "resource": {
        "resourceType": "ServiceRequest",
        "id": "order-1",
        "status": "active",
        "intent": "order",
        "subject": {
          "reference": "Patient/patient-1"
        },
        "code": {
          "coding": [
            {
              "system": "http://www.ama-assn.org/go/cpt",
              "code": "00000"
            }
          ]
        }
      }
    },
    {
      "name": "referenced",
      "resource": {
        "resourceType": "Patient",
        "id": "patient-1"
      }
    }
  ]
}

The request is illustrative. Consumers must use valid production codes and the exact Parameters profile and resource packaging rules published by CareFirst.

Illustrative next-question request

{
  "resourceType": "QuestionnaireResponse",
  "id": "qr-1",
  "questionnaire": "https://example.org/fhir/Questionnaire/questionnaire-123",
  "status": "in-progress",
  "subject": {
    "reference": "Patient/patient-1"
  },
  "item": [
    {
      "linkId": "1",
      "answer": [
        {
          "valueBoolean": true
        }
      ]
    }
  ]
}

Illustrative log-questionnaire-errors request

{
  "resourceType": "Parameters",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-log-errors-input-parameters"
    ]
  },
  "parameter": [
    {
      "name": "Questionnaire",
      "valueCanonical": "https://example.org/fhir/Questionnaire/questionnaire-123|1.0"
    },
    {
      "name": "OperationOutcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "The DTR client could not render the coded answer control."
            },
            "expression": [
              "Questionnaire.item.where(linkId='coverage-type')"
            ]
          }
        ]
      }
    }
  ]
}

The example deliberately excludes patient and clinical data. The submitted OperationOutcome must not contain PHI or information retrieved from FHIR APIs.

4 Supported Capabilities

Questionnaire package

• Accept a DTR questionnaire-package Parameters request.
• Validate required parameters and resolvable FHIR resources.
• Resolve the member from Coverage.
• Determine HOME, HOST, CFA, and applicable inter-plan routing.
• For eligible CareFirst members, evaluate CareFirst rules to determine coverage, PA requirement, medical-criteria need, and questionnaire vendor.
• Route eligible requests to MCG/HealthEdge, Carelon, EviCore, or the BCBSA Interoperability Hub.
• Return a Questionnaire Package Bundle containing Questionnaire resources and applicable Library, ValueSet, or other supporting resources.
• Consolidate multiple returned questionnaires into a single package when supported.
• Cache adaptive questionnaire routing context for later $next-question calls.
• Cache questionnaire canonical URL routing information for applicable questionnaire-error workflows.

Adaptive next question

• Accept a QuestionnaireResponse for an active adaptive questionnaire.
• Validate the resource, questionnaire reference, and in-progress status.
• Resolve the vendor and session from CareFirst-managed cache.
• Route the answers to the vendor associated with the originating questionnaire.
• For a BCBSA session, include the cached session UUID in the downstream route.
• Normalize vendor-specific responses into a consistent FHIR R4 questionnaire Bundle.
• Return the next question set or an indication that the adaptive questionnaire is complete.

ValueSet expansion

• Accept GET /{uuid}/ValueSet/$expand for an applicable BCBSA terminology session.
• Validate that the UUID path segment is present and structurally valid.
• Forward the original expansion query to the BCBSA terminology endpoint.
• Return the expanded ValueSet or upstream error response without changing its clinical meaning.

Log questionnaire errors

• Accept POST /Questionnaire/$log-questionnaire-errors with a FHIR Parameters body.
• Validate conformance to the DTR Log Questionnaire Errors Input Parameters profile.
• Require one Questionnaire canonical parameter and one FHIR R4 OperationOutcome parameter.
• Use the Questionnaire canonical URL to look up the vendor associated with the session created during $questionnaire-package.
• Forward the original request body without transformation when the cached vendor is BCBSA.
• Record the error in the CareFirst audit table when the session is unknown or expired, Redis is unavailable, or the resolved vendor is MCG, Carelon, or EviCore.
• Return an HTTP 200 acknowledgement for locally handled reports. The acknowledgement does not disclose whether the report was forwarded or only audited.
• Retry a BCBSA 5xx response or timeout up to three times using exponential backoff. If delivery still fails, record the report locally and return HTTP 200 with an OperationOutcome explaining that delivery to the inter-plan hub was unsuccessful.
• Treat audit persistence as non-blocking. If the audit write fails, CareFirst logs the failure and still acknowledges the EHR request.

Illustrative HTTP requests

POST /Questionnaire/$questionnaire-package HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

POST /Questionnaire/$next-question HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

POST /Questionnaire/$log-questionnaire-errors HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

GET /{uuid}/ValueSet/$expand?url={encoded-canonical-url} HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Accept: application/fhir+json

Illustrative questionnaire-package response

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Questionnaire",
        "id": "questionnaire-123",
        "url": "https://example.org/fhir/Questionnaire/questionnaire-123",
        "status": "active",
        "subjectType": ["Patient"],
        "item": [
          {
            "linkId": "1",
            "text": "Example clinical question",
            "type": "boolean"
          }
        ]
      }
    }
  ]
}

5 Limitations

• DTR retrieves and completes documentation questionnaires. It does not submit or approve prior authorization.
• Order-based questionnaire-package processing currently supports ServiceRequest and DeviceRequest. Other order resource types may be rejected unless the published contract explicitly supports them.
• Procedure and diagnosis coding is limited to the code systems supported by CareFirst and the selected downstream vendor.
• A questionnaire is returned only when the applicable coverage, PA, medical-criteria, routing, and vendor conditions are satisfied.
• A service identified as not covered, not requiring authorization, or not requiring medical-criteria documentation may not proceed to a questionnaire vendor.
• Multi-order behavior is vendor dependent. Consumers must follow the release-specific CareFirst contract and must be prepared to submit one order at a time if required.
• Carelon request and response details may remain release dependent until the final integration contract is published.
• EviCore may require CareFirst to transform externally referenced resources into contained resources. Consumers should still submit complete, resolvable references according to the CareFirst input contract.
• Adaptive continuation depends on CareFirst cache state. A missing or expired session requires the consumer to restart with $questionnaire-package.
• The $expand proxy supports the applicable BCBSA terminology route only. It is not a general-purpose terminology service.
• Error-report forwarding is currently supported only for BCBSA sessions. MCG, Carelon, and EviCore questionnaire errors are recorded in the CareFirst audit trail but are not forwarded to those vendors.
• Error routing depends on the Questionnaire canonical URL matching the value cached during $questionnaire-package. An unknown, changed, or expired URL follows the local audit path.
• CareFirst validates the structure of the submitted OperationOutcome but does not validate every diagnostic content recommendation. The EHR remains responsible for useful diagnostics and exclusion of PHI.
• A successful acknowledgement does not indicate whether the report was forwarded to BCBSA, stored locally, or encountered a non-blocking audit-write failure.
• CareFirst does not validate a structurally valid $expand UUID against a local session registry before forwarding. The upstream BCBSA service may reject an unknown session.
• Vendor availability and response time can affect all three operations.
• The exact handling of HTTP status versus OperationOutcome differs by scenario. Consumers must inspect both.
• Endpoint URLs, token scopes, cache lifetime, request-size limits, rate limits, retry intervals, and service-level objectives are environment and release specific.
• Consumers must not depend on vendor-specific extensions unless they are explicitly retained in the CareFirst contract.

6 Typical Interaction

Standard questionnaire workflow

1. A provider identifies a service for which documentation may be required.
2. The EHR creates a FHIR Parameters request containing Coverage, the supported order, and referenced clinical resources.
3. The EHR calls POST /Questionnaire/$questionnaire-package.
4. CareFirst validates the request and resolves the member.
5. CareFirst determines plan routing and the applicable questionnaire vendor.
6. CareFirst evaluates coverage, prior authorization, and medical-criteria requirements when applicable.
7. CareFirst calls the selected questionnaire source.
8. CareFirst returns a FHIR Bundle containing the Questionnaire and supporting artifacts.
9. The EHR renders the Questionnaire and records answers in a QuestionnaireResponse.
10. The completed documentation is retained for the appropriate downstream prior authorization workflow.

Adaptive questionnaire workflow

1. The EHR retrieves a questionnaire package.
2. CareFirst stores the questionnaire-to-vendor/session routing context for an adaptive Questionnaire.
3. The provider answers the displayed questions.
4. The EHR sends the in-progress QuestionnaireResponse to POST /Questionnaire/$next-question.
5. CareFirst resolves the session from the Questionnaire reference.
6. CareFirst routes the response to the applicable vendor and normalizes the returned artifacts.
7. The EHR renders the next questions.
8. Steps 3 through 7 repeat until the questionnaire is complete.
9. If the session is missing or expired, the EHR restarts the workflow using $questionnaire-package.

ValueSet expansion workflow

1. The EHR renders a BCBSA questionnaire that references an external ValueSet.
2. The questionnaire package supplies or references a terminology base URL containing a session UUID.
3. The EHR calls GET /{uuid}/ValueSet/$expand with the required expansion parameters.
4. CareFirst validates the request structure and forwards it to the BCBSA terminology service.
5. CareFirst returns the expanded ValueSet or the upstream error response.
6. The EHR uses the resulting concepts to populate the coded answer control.

Questionnaire error-reporting workflow

1. The EHR detects an error while rendering a Questionnaire, resolving a ValueSet, evaluating questionnaire logic, or submitting a QuestionnaireResponse.
2. The EHR creates a FHIR Parameters resource containing the original Questionnaire canonical URL and a PHI-free OperationOutcome.
3. The EHR calls POST /Questionnaire/$log-questionnaire-errors.
4. CareFirst validates the Parameters resource and both required parameters.
5. CareFirst uses the Questionnaire canonical URL to look up the cached vendor session.
6. If the vendor is BCBSA, CareFirst forwards the original payload to the BCBSA Interoperability Hub.
7. If the cache misses, Redis is unavailable, or the vendor is MCG, Carelon, or EviCore, CareFirst records the report in its audit trail without downstream forwarding.
8. CareFirst returns the applicable acknowledgement or OperationOutcome.

$questionnaire-package
  -> Validate FHIR Parameters
  -> Resolve Coverage and member
  -> Determine plan and vendor route
  -> Retrieve questionnaire package
  -> Cache adaptive routing context
  -> Return FHIR Bundle

$next-question
  -> Validate QuestionnaireResponse
  -> Resolve cached session/vendor
  -> Forward answers
  -> Normalize next-question package
  -> Return next questions or completion

$expand
  -> Validate UUID and method
  -> Forward query to BCBSA terminology service
  -> Return expanded ValueSet or upstream error

$log-questionnaire-errors
  -> Validate Parameters, Questionnaire canonical, and OperationOutcome
  -> Look up vendor by Questionnaire canonical URL
  -> BCBSA: forward original report
  -> Cache miss or non-BCBSA: write CareFirst audit record
  -> Return acknowledgement or applicable OperationOutcome

7 Core Schema Elements

Questionnaire-package request

Questionnaire package and adaptive response

ValueSet expansion

Log questionnaire errors

Consumer interpretation rules

• Retain Questionnaire IDs and canonical URLs exactly as returned.
• Do not invent or replace the BCBSA session UUID.
• Resolve and preserve references in the questionnaire-package request.
• Treat Questionnaire items and enablement logic as authoritative display and answer constraints.
• Preserve answer data types in QuestionnaireResponse.
• A Bundle containing an OperationOutcome is not a successful questionnaire package.
• When a Questionnaire indicates adaptive behavior, use the CareFirst adaptive endpoint supplied by the package or environment contract.
• Use the exact Questionnaire canonical URL in $log-questionnaire-errors; changing the URL or version can prevent session resolution.
• Never include PHI or provider-FHIR-retrieved information in an error-report OperationOutcome.
• Treat the log operation as telemetry and audit reporting, not as a request to resume, correct, or approve the questionnaire workflow.

8 Validation and Error Handling

Common validation

Questionnaire-package validation

Next-question validation

ValueSet expansion validation

Log-questionnaire-errors validation and routing

Illustrative OperationOutcome

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "QuestionnaireResponse.questionnaire is required."
      }
    }
  ]
}

Consumer error-handling requirements

• Inspect both the HTTP status and the FHIR resource type in the response.
• Treat OperationOutcome as an unsuccessful business result unless the CareFirst contract explicitly states otherwise.
• Do not retry structural validation, unsupported-code, member-resolution, or business-rule failures without correcting the request.
• Retry transient failures only when permitted, using bounded backoff and the original correlation context.
• If an adaptive session has expired, restart with $questionnaire-package rather than repeatedly calling $next-question.
• Do not retry $expand 4xx responses unless the request or session information has been corrected.
• Log only approved diagnostic data, such as timestamp, operation name, non-PHI correlation identifiers, HTTP status, and OperationOutcome code.
• Do not log tokens, secrets, entire clinical payloads, or member data without explicit CareFirst authorization.
• Do not retry a successfully acknowledged $log-questionnaire-errors request merely because the response does not identify the internal route.
• Remove PHI before submitting a questionnaire error report.

1. Overview

The CareFirst Prior Authorization Support (PAS) API enables an Electronic Health Record (EHR), provider application, or authorized trading partner to submit, update, and inquire about prior authorization requests using HL7 FHIR R4 and the Da Vinci PAS 2.1 implementation model.

The PAS API provides two consumer-facing operations:

• POST /Claim/$submit creates a new prior authorization request or updates an existing request.
• POST /Claim/$inquiry searches for existing authorization decisions and statuses.

The business objective is to provide a standards-based prior authorization channel that validates structured clinical and administrative information, routes requests to the appropriate CareFirst or delegated vendor workflow, returns structured authorization responses, and supports subsequent status inquiries.

For $submit, CareFirst determines whether the request is a create or update, validates the PAS Claim Bundle, resolves the member and plan, evaluates authorization rules, identifies the responsible vendor, and routes the request to EviCore, Carelon, HealthEdge/GuidingCare, or the BCBSA Interoperability Hub as applicable.

For $inquiry, CareFirst validates the search criteria, resolves the member, routes non-CareFirst members to the BCBSA Interoperability Hub, obtains CareFirst authorization records from the Advanced Healthcare Data Store (AHDS), obtains applicable EviCore records, applies provider, service-date, and procedure-code filters, and returns a FHIR searchset Bundle of ClaimResponse resources.

Authorization decisions originating in GuidingCare are persisted asynchronously in AHDS as PAS 2.1 ClaimResponse resources. This supports future inquiry requests and notification workflows. This ingestion process is internal and is not a third-party API operation.

A successful transport response does not always mean that an authorization was approved. Consumers must inspect the returned ClaimResponse outcome, adjudication, decision codes, process notes, and errors. A queued response indicates that processing is pending and does not include a final authorization decision.

This document is a consumer-facing integration guide. The CareFirst-published API contract, FHIR profiles, OpenAPI definition, onboarding materials, and environment-specific specifications remain authoritative for URLs, headers, scopes, cardinalities, code bindings, and release-specific behavior.

2. API Profile

Operation summary

Create versus update

3 Prerequisites

Before integrating with the PAS API, a third-party consumer must complete the following prerequisites.

1. Application onboarding
   • Register the organization and application through the CareFirst API onboarding process.
   • Obtain PAS entitlement for every required environment.
   • Complete required security, privacy, legal, interoperability, and connectivity reviews.
   • Obtain the environment-specific base URL, OAuth token endpoint, API key, scopes, support contacts, and applicable BCBSA inter-plan requirements.
2. Authentication and transport
   • Implement OAuth 2.0 Client Credentials using CareFirst-issued credentials.
   • Send the bearer token and required API access headers with every request.
   • Use HTTPS and the CareFirst-approved TLS configuration.
   • Store secrets in an approved secret store. Do not place credentials or tokens in source code, URLs, application telemetry, or user-facing messages.
3. FHIR and PAS conformance
   • Send and receive application/fhir+json.
   • Build requests using FHIR R4 and the CareFirst-supported Da Vinci PAS 2.1 profiles.
   • Preserve Bundle fullUrl values and ensure all internal references resolve correctly.
   • Use the exact CareFirst-published canonical profiles, extension URLs, code systems, value sets, and operation definitions.
   • Support FHIR Bundle, Claim, ClaimResponse, Patient, Coverage, Organization, Practitioner, PractitionerRole, Location, DocumentReference, Parameters, and OperationOutcome resources as applicable.
   • Validate requests locally before transmitting them.
4. Submit request requirements
   • Send a collection Bundle containing one focal Claim and all required supporting resources.
   • Set Claim.use to preauthorization.
   • Set Claim type to professional or institutional using http://terminology.hl7.org/CodeSystem/claim-type.
   • Include a resolvable Patient and Coverage.
   • Populate Coverage.subscriberId whenever available. If it is absent, supply a Coverage identifier with type code MB.
   • Include at least one patient name and a valid Patient.birthDate.
   • Include an ICD-10-CM diagnosis.
   • On every service line, include a supported CPT or HCPCS code, service date or period, CMS Place of Service code, quantity greater than zero, and applicable unit or code.
   • Include required requesting, referring, servicing, facility, or admitting provider information according to claim type and authorization class.
   • Include Organization Tax ID as required by the CareFirst contract.
   • For HealthEdge/GuidingCare routing, include the servicing provider in Claim.careTeam with role code SJ.
   • For inpatient requests, include admission dates and use Days as the unit type on the first authorization line, with the remaining lines populated according to the CareFirst inpatient rule.
5. Create and update correlation
   • For a create request, omit Claim.related.claim unless the CareFirst contract requires another permitted relationship.
   • For an update request, populate Claim.related.claim.reference with the Claim identifier associated with the original create request.
   • Retain the Claim reference and authorization identifiers returned from the create workflow.
   • Do not submit an update before a successful create has been registered in CareFirst systems.
   • Carelon updates are not supported. Submit a new authorization when instructed by the rejection response.
   • For updated or added lines, populate the PAS information-changed extension and preserve the original decision sequence information when required.
   • For line removal or authorization cancellation, use the CareFirst-supported PAS cancellation/certification extensions.
   • Existing attachments cannot be replaced or cancelled through the current update workflow. New or changed supporting information is treated as an addition.
6. Supporting documentation
   • Include supporting documents through the Claim supporting-information structure required by the CareFirst PAS contract.
   • Populate attachment contentType, data, and title when available.
   • Supported formats include common PDF, image, Microsoft Office, text, CSV, XML, JSON, FHIR, ZIP, CDA, HL7, and signed-document formats.
   • Unsupported or missing MIME types may be mapped to TXT for the GuidingCare path. Consumers should therefore send a valid MIME type whenever possible.
   • Do not exceed environment-specific payload and attachment limits.
7. Inquiry request requirements
   • Use one of the supported inquiry search modes described below.
   • For member-based searches, provide Subscriber ID, date of birth, and the name elements required by the CareFirst contract.
   • Include provider NPI and Organization Tax ID when provider filtering applies.
   • If an Administrative Reference Number is provided on multiple lines, use the same value on every line.
   • Provide CPT/HCPCS codes and requested service dates only when they should constrain the search.
   • Do not use insurer as an inquiry filter. If present, it is ignored.
   • Be prepared to receive an empty searchset Bundle when no authorization matches.
8. Operational readiness
   • Generate and propagate the correlation identifiers required by the environment contract.
   • Implement safe timeout and retry handling.
   • Do not place PHI in URLs, correlation identifiers, analytics, or unapproved logs.
   • Inspect both HTTP status and FHIR response content.
   • Support ClaimResponse outcomes including queued and error.
   • Preserve request identifiers so queued responses can be followed through the inquiry or notification workflow.

Illustrative submit request

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:claim-1",
      "resource": {
        "resourceType": "Claim",
        "id": "claim-1",
        "status": "active",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",
              "code": "professional"
            }
          ]
        },
        "use": "preauthorization",
        "patient": { "reference": "urn:uuid:patient-1" },
        "insurer": { "reference": "urn:uuid:insurer-1" },
        "provider": { "reference": "urn:uuid:provider-role-1" },
        "priority": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/processpriority",
              "code": "normal"
            }
          ]
        },
        "diagnosis": [
          {
            "sequence": 1,
            "diagnosisCodeableConcept": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/sid/icd-10-cm",
                  "code": "Z00.00"
                }
              ]
            }
          }
        ],
        "item": [
          {
            "sequence": 1,
            "productOrService": {
              "coding": [
                {
                  "system": "http://www.ama-assn.org/go/cpt",
                  "code": "00000"
                }
              ]
            },
            "servicedDate": "2026-10-01",
            "locationCodeableConcept": {
              "coding": [
                {
                  "system": "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
                  "code": "11"
                }
              ]
            },
            "quantity": {
              "value": 1,
              "unit": "unit"
            }
          }
        ]
      }
    },
    {
      "fullUrl": "urn:uuid:patient-1",
      "resource": {
        "resourceType": "Patient",
        "id": "patient-1",
        "name": [{ "family": "Example", "given": ["Patient"] }],
        "birthDate": "1980-01-01"
      }
    },
    {
      "fullUrl": "urn:uuid:coverage-1",
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-1",
        "status": "active",
        "subscriberId": "ABC123456789",
        "beneficiary": { "reference": "urn:uuid:patient-1" }
      }
    }
  ]
}

The sample is intentionally abbreviated and uses a placeholder procedure code. It is not a production-ready PAS Bundle. Consumers must include all resources, extensions, identifiers, and references required by the published CareFirst PAS profile.

4 Supported Capabilities

Submit a new authorization

• Accept a Da Vinci PAS 2.1 Claim Bundle at POST /Claim/$submit.
• Validate FHIR structure, required fields, cardinalities, references, and code bindings.
• Resolve Subscriber ID from Coverage.subscriberId or the MB Coverage identifier.
• Support professional and institutional claims.
• Validate member, diagnosis, procedure, service date, location, quantity, unit, and provider information.
• Determine member plan routing using subscriber-prefix and plan-profile logic.
• Route HOST requests to the BCBSA Interoperability Hub.
• Reject unsupported CFA and applicable inbound FEP PPO scenarios.
• Evaluate CareFirst authorization rules for eligible requests.
• Route requests to EviCore, Carelon, or HealthEdge/GuidingCare based on the rules result.
• Return vendor decisions without changing their clinical meaning.
• Return a queued ClaimResponse when a configured synchronous timeout or applicable 503 condition occurs.
• Return structured inline PAS rejection Bundles for correctable business-data issues.

Update an existing authorization

• Identify an update through Claim.related.claim.
• Resolve the original authorization and vendor from CareFirst claim correlation data.
• Reject an update when the prior create cannot be found.
• Reject Carelon updates and direct the caller to create a new request.
• Ensure the vendor determined for the update matches the vendor used for the original create.
• Support adding or changing a service line.
• Support removing a service line using the applicable PAS cancellation/certification extension.
• Support cancelling an entire authorization.
• Support adding new or changed supporting information.
• Preserve the original line decision sequence where required.

Inquire about authorization status

• Accept POST /Claim/$inquiry.
• Support direct Administrative Reference Number searches.
• Support Member + Provider searches.
• Support optional procedure-code filtering.
• Support optional requested-service-date filtering.
• Support combined Administrative Reference Number, Member, Provider, procedure-code, and service-date criteria.
• Route non-CareFirst member inquiries to the BCBSA Interoperability Hub.
• Resolve CareFirst member identity and deterministic AHDS Patient ID.
• Query AHDS and EviCore in parallel for eligible CareFirst inquiries.
• Deduplicate results by authorization identifier, with AHDS taking precedence.
• Apply provider, service-date, and procedure-code filters.
• Return a FHIR searchset Bundle.
• Return HTTP 200 with total: 0 for a valid search with no matches.
• Include Organization or Practitioner/Organization/PractitionerRole resources needed to resolve provider references.

Supported inquiry modes

Illustrative HTTP requests

POST /Claim/$submit HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

POST /Claim/$inquiry HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

Illustrative queued response

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "ClaimResponse",
        "status": "active",
        "use": "preauthorization",
        "patient": { "reference": "Patient/patient-1" },
        "insurer": { "reference": "Organization/insurer-1" },
        "request": { "reference": "Claim/claim-1" },
        "outcome": "queued"
      }
    }
  ]
}

A queued response indicates that a final decision was not available within the synchronous processing window. It is not an approval. Consumers should retain the Claim identifier and use the approved inquiry or notification process to obtain the final result.

Illustrative empty inquiry response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

5 Limitations

• Only professional and institutional Claim types are supported.
• PAS submission supports the CareFirst-published Da Vinci PAS 2.1 profile. Other FHIR claim profiles are not accepted unless explicitly documented.
• A transport-level HTTP 200 response may contain an inline rejection ClaimResponse with outcome: error.
• A queued ClaimResponse is not a final decision and may not contain an authorization number.
• Carelon update requests are not supported.
• Update routing requires a valid prior Claim correlation in CareFirst claim data.
• A vendor change between create and update is not supported. The consumer must submit a new authorization when instructed.
• Existing supporting documents cannot currently be replaced or cancelled through the update operation.
• Unsupported attachment MIME types may be converted to text for the GuidingCare route.
• HOST processing depends on the BCBSA Interoperability Hub.
• EviCore and Carelon processing depends on vendor availability and vendor-specific validation.
• Inquiry insurer filtering is not supported.
• Inquiry queries are capped by the CareFirst AHDS result limit. The referenced design uses _count=100; pagination behavior remains release specific.
• Inquiry service-date and procedure-code filtering may be performed after records are retrieved.
• EviCore inquiry failure is non-blocking. When it fails, the response may contain AHDS results only.
• A valid inquiry with no matches returns an empty searchset, not HTTP 404.
• Final denial-reason crosswalks and some vendor-specific mappings may remain release dependent.
• Endpoint URLs, OAuth scopes, headers, total timeout budget, retry counts, request-size limits, attachment-size limits, rate limits, and service levels are environment specific.

6 Typical Interaction

Submit create workflow

1. The EHR constructs a PAS 2.1 collection Bundle containing the Claim and supporting resources.
2. The EHR calls POST /Claim/$submit.
3. CareFirst authenticates the caller and validates the PAS Bundle.
4. CareFirst resolves Subscriber ID and validates Claim type.
5. Because Claim.related.claim is absent, CareFirst classifies the request as create.
6. CareFirst validates patient identity, diagnosis, service codes, dates, locations, quantities, units, and provider information.
7. CareFirst derives the member prefix and determines HOME, HOST, CFA, or applicable special routing.
8. HOST requests are forwarded to the BCBSA Interoperability Hub. Eligible HOME requests continue to CareFirst authorization rules.
9. CareFirst determines the delegated vendor.
10. The request is routed to EviCore, Carelon, or HealthEdge/GuidingCare.
11. CareFirst returns a decision Bundle, inline rejection Bundle, queued acknowledgement, or OperationOutcome.
12. The consumer inspects ClaimResponse outcome and decision details rather than relying on HTTP status alone.

Submit update workflow

1. The EHR includes Claim.related.claim.reference for the original Claim.
2. CareFirst resolves the prior authorization and original vendor.
3. If no prior create exists, CareFirst rejects the update.
4. If the original vendor is Carelon, CareFirst returns a structured rejection requiring a new authorization.
5. Standard submit validations and authorization rules are evaluated.
6. CareFirst verifies that the current vendor matches the original vendor.
7. CareFirst applies supported line, cancellation, or supporting-information update logic.
8. The applicable downstream system processes the update.
9. CareFirst returns the resulting PAS response.

Inquiry workflow

1. The EHR constructs the inquiry request with a supported criteria combination.
2. The EHR calls POST /Claim/$inquiry.
3. CareFirst validates member information and Administrative Reference Number consistency.
4. CareFirst determines CareFirst versus non-CareFirst routing.
5. Non-CareFirst inquiries are forwarded to the BCBSA Interoperability Hub.
6. For a CareFirst member, CareFirst resolves MemberLifeID and generates the AHDS Patient ID.
7. CareFirst queries AHDS and EviCore in parallel.
8. CareFirst combines and deduplicates the results.
9. CareFirst applies provider, service-date, and procedure-code filters.
10. CareFirst builds a searchset Bundle and resolves provider references.
11. CareFirst returns matching ClaimResponses or an empty searchset.

$submit
  -> Authenticate and validate PAS Bundle
  -> Resolve subscriber and claim type
  -> Classify create or update
  -> Apply required-field validations
  -> Determine plan route
  -> Evaluate authorization rules
  -> Select vendor
  -> Return decision, rejection, queued response, or OperationOutcome

$inquiry
  -> Authenticate and validate search request
  -> Resolve member and plan route
  -> Query AHDS and EviCore when applicable
  -> Deduplicate and filter results
  -> Resolve provider references
  -> Return searchset Bundle

Internal ClaimResponse persistence

Authorization events from GuidingCare are transformed internally into Da Vinci PAS 2.1 ClaimResponse resources and stored in AHDS. The internal process enriches provider details, resolves the related Claim where possible, maps authorization and line decisions to X12 review-action codes, persists the ClaimResponse, and publishes a thin notification event after a successful write. Third-party consumers do not call this persistence flow directly.

7 Core Schema Elements

Submit request

Submit response

Inquiry request and response

Decision and error interpretation

• Header and line-level authorization decisions can be represented with X12 review-action codes.
• Typical decision mappings include approved, partially approved, denied, pending, and cancelled states.
• Inline rejections use ClaimResponse processNote and error with PAS error-element and follow-up-action extensions.
• An OperationOutcome generally indicates that the request could not proceed as a valid PAS business transaction.
• A ClaimResponse with outcome: error is a processed PAS rejection and may be returned with HTTP 200.
• A ClaimResponse with outcome: queued indicates pending processing.

8 Validation and Error Handling

Common transport and structure validation

Submit business validation

Update validation

Inquiry validation

Illustrative inline rejection

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "ClaimResponse",
        "status": "active",
        "use": "preauthorization",
        "outcome": "error",
        "processNote": [
          {
            "number": 1,
            "text": "The request is missing information required for prior authorization processing."
          }
        ],
        "error": [
          {
            "extension": [
              {
                "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-errorElement",
                "valueString": "2000E"
              },
              {
                "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-errorFollowupAction",
                "valueCodeableConcept": {
                  "coding": [
                    {
                      "system": "https://codesystem.x12.org/005010/889",
                      "code": "C"
                    }
                  ]
                }
              }
            ],
            "code": {
              "coding": [
                {
                  "system": "https://codesystem.x12.org/005010/901",
                  "code": "33"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

The exact error element, follow-up action, reason code, and process note depend on the failed validation and the published CareFirst mapping.

Consumer error-handling requirements

• Inspect the HTTP status, top-level FHIR resource type, ClaimResponse outcome, process notes, adjudication, and error elements.
• Do not treat HTTP 200 as approval.
• Do not treat queued as approval or denial.
• Do not retry structural or business validation failures without correcting the request.
• Do not automatically retry vendor 4xx responses.
• Retry transient errors only when permitted by the CareFirst contract and use bounded backoff.
• Retain the same business identifiers and correlation context for permitted retries.
• When a queued response is returned, retain the Claim identifier and use inquiry or the approved notification workflow.
• Log only approved operational data. Do not log tokens, secrets, complete clinical payloads, full member identifiers, or attachments unless explicitly permitted.
• When the result is unavailable or ambiguous, do not represent the service as authorized or guaranteed to be covered or paid.

1. Overview

The CareFirst Prior Authorization Subscription and Notification API enables a provider Electronic Health Record (EHR), authorized provider application, or the BCBSA Interoperability Hub to register for and receive FHIR-based prior authorization status notifications.

The business objective is to notify a provider when a previously submitted prior authorization request changes, especially when the original PAS response was pended or queued, without requiring the provider to poll repeatedly for an updated decision.

The API combines two related capabilities:

• Subscription management, used to create and update the organization’s subscription, filter criteria, callback endpoint, payload preference, and delivery headers.
• Notification delivery, used by CareFirst to send handshake and prior authorization event notifications to the registered endpoint.

The consumer-facing operations are:

• POST /Subscription to create a subscription.
• PUT /Subscription/{id} to replace or update an existing subscription.
• POST /Subscription/$status to retrieve the current subscription lifecycle status.
• DELETE /Subscription/{id} to deactivate an existing subscription.
• POST /$notification-hook as the callback operation that the subscriber must expose to receive handshake and event-notification Bundles.

CareFirst generates the Subscription identifier, persists the subscription and filters, verifies a provider callback endpoint by sending a handshake notification, and updates the subscription status based on the handshake result. For provider-originated subscriptions, CareFirst also coordinates applicable inter-plan registration with BCBSA. For an update, CareFirst detects filter and endpoint changes and invokes only the required downstream actions. The $status operation provides read-only lifecycle visibility. The delete operation performs a soft delete by setting the subscription status to off; the subscription and filter records remain available for audit.

When a prior authorization event is received from CareFirst systems, a delegated vendor, or BCBSA, CareFirst acknowledges the source, matches active subscriptions using registered organization identifiers such as NPI or Tax ID, constructs a FHIR notification Bundle, and delivers it to each matching callback endpoint. The inbound acknowledgement is separated from the asynchronous matching and outbound delivery process.

A successful subscription response means that the registration request was accepted and persisted. Consumers must inspect Subscription.status. A status of requested means endpoint verification may still be pending. A status of error means the endpoint or another subscription activity failed. A notification acknowledgement confirms receipt by the callback endpoint and does not represent an authorization decision.

This document is a third-party integration guide. The CareFirst-published OpenAPI contract, FHIR profiles, onboarding materials, and environment-specific specifications remain authoritative for base URLs, OAuth scopes, headers, callback allowlisting, filter syntax, timeouts, retry behavior, and release-specific requirements.

2. API Profile

Operation summary

Subscription status interpretation

3 Prerequisites

Before integrating with the API, a third-party consumer must complete the following prerequisites.

1. Application onboarding
   • Register the organization and application through the CareFirst API onboarding process.
   • Obtain the Subscription and Notification product entitlement for every environment.
   • Complete required security, privacy, legal, connectivity, and callback-endpoint reviews.
   • Obtain the base URL, OAuth token endpoint, API key, scopes, required source headers, and support contacts.
2. Authentication and transport
   • Implement OAuth 2.0/JWT as defined by the CareFirst environment contract.
   • Send the bearer token, API access key, and required correlation headers on subscription-management requests.
   • Use HTTPS and the CareFirst-approved TLS configuration.
   • Store credentials and callback secrets in an approved secret store.
   • Do not put access tokens, secrets, PHI, or sensitive identifiers in URLs or unapproved logs.
3. FHIR Subscription support
   • Send and receive application/fhir+json.
   • Build the Subscription using the CareFirst-supported PAS Subscription profile.
   • Use the PAS SubscriptionTopic canonical URL required by the published contract.
   • Use a REST-hook channel.
   • Supply a valid HTTPS channel.endpoint that can receive POST requests from the CareFirst-approved network path.
   • Include at least one organization filter. The filter identifies the organization for which notifications will be delivered.
   • Use NPI and/or Tax ID filter systems and values exactly as defined in the CareFirst contract.
   • Provide the complete desired header set. Headers are stored as a complete map and are not partially merged during an update.
   • Request the supported payload type, normally application/fhir+json with full-resource content.
4. Callback endpoint implementation
   • Expose POST /$notification-hook, or provide an equivalent callback URL accepted by CareFirst onboarding.
   • Accept a FHIR Bundle of type history.
   • Support both handshake and event-notification values in the Parameters resource.
   • Return an HTTP 2xx response only after the message has been validated sufficiently and durably accepted for processing.
   • Make the callback idempotent. The same notification may be delivered more than once.
   • Do not assume notifications arrive in event-number order.
   • Correlate the message using the Subscription reference, event number, notification timestamp, and PAS Bundle identifiers.
   • Process the PAS ClaimResponse Bundle included as the event focus.
   • Preserve unknown FHIR extensions and supporting resources unless the published profile states otherwise.
5. Callback connectivity
   • Ensure the registered endpoint is reachable from the approved CareFirst/APIM network route.
   • Complete any IP allowlisting, DNS, certificate, and firewall configuration required during onboarding.
   • Use a production-grade TLS certificate with a valid trust chain and matching host name.
   • Do not redirect the callback to an unregistered domain.
   • Keep the endpoint available during the handshake and subsequent event delivery.
6. Create-request requirements
   • Do not assign or depend on the inbound Subscription.id; CareFirst generates the authoritative GUID for a new subscription.
   • Include the subscription topic, reason, filter criteria, callback endpoint, headers when needed, and payload preference.
   • Understand that CareFirst initially stores a provider-originated subscription with status requested and changes it to active only after a successful handshake.
   • Retain the CareFirst-assigned Subscription ID returned by the create operation.
7. Update-request requirements
   • For a provider-originated update, use the CareFirst Subscription ID as {id}.
   • Send the complete updated Subscription resource, not only changed fields.
   • Continue to include at least one filter and a valid callback endpoint.
   • Retain the original source and any BCBSA correlation data. The update operation does not replace those values.
   • Recognize that a filter change can trigger inter-plan synchronization.
   • Recognize that an endpoint change resets status to requested and triggers asynchronous handshake verification after the HTTP 200 response.
8. Status and delete support
   • Retain the CareFirst Subscription ID returned by create. Providers use this ID for $status, update, and delete.
   • Build the $status request as a FHIR Parameters resource containing parameter[name="id"].valueId.
   • Do not include a request body with DELETE. Supply the identifier in the path.
   • For provider requests, the identifier is the internal CareFirst Subscription GUID. For BCBSA-originated requests, the identifier is the BCBSA correlation ID.
   • Interpret delete as deactivation, not physical removal. CareFirst sets status to off and retains the subscription and filters for audit.
   • Treat delete as idempotent. Deleting a subscription already in off status returns HTTP 200 without additional downstream calls.
9. Security and privacy for notification payloads
   • Treat notification payloads as PHI-bearing clinical transactions.
   • Encrypt stored payloads and limit access to authorized users and services.
   • Avoid logging the full Bundle unless explicitly permitted by the organization’s CareFirst-approved logging controls.
   • Validate the inbound connection and any agreed CareFirst routing or identification headers.
   • Do not make authorization decisions from transport metadata alone. Inspect the ClaimResponse in the focus Bundle.

Illustrative create request

{
  "resourceType": "Subscription",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscription"
    ]
  },
  "status": "requested",
  "reason": "Receive notifications about prior authorization ClaimResponse updates.",
  "criteria": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic",
  "_criteria": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
        "valueString": "orgIdentifier=http://hl7.org/fhir/sid/us-npi|1234567890"
      }
    ]
  },
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://ehr.example.org/fhir/$notification-hook",
    "payload": "application/fhir+json",
    "_payload": {
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
          "valueCode": "full-resource"
        }
      ]
    }
  }
}

The example is illustrative. Use the exact filter syntax, identifier systems, Subscription profile, and payload extension required by the CareFirst release contract.

4 Supported Capabilities

Create a subscription

• Accept POST /Subscription from an authorized provider system or BCBSA route.
• Validate the presence of at least one filter criterion.
• Validate that channel.endpoint is present and is a supported HTTP or HTTPS URL.
• Generate the authoritative Subscription GUID.
• Determine whether the source is PROVIDER or BCBSA using approved source-identification headers.
• Persist the Subscription and one filter record for every filter criterion.
• For a provider-originated request, preserve the provider endpoint and register applicable subscription information through the inter-plan route.
• For a BCBSA-originated request, use the internal CareFirst inbound notification endpoint for routed delivery.
• Send a FHIR handshake notification to the stored endpoint after persistence.
• Change the subscription status to active after a successful handshake.
• Change the subscription status to error and store error details after a failed handshake.
• Return the generated Subscription ID to the caller.

Update a subscription

• Accept PUT /Subscription/{id}.
• For provider requests, locate the record by CareFirst Subscription ID.
• For BCBSA requests, locate the record by BCBSA correlation ID.
• Return HTTP 404 when the Subscription cannot be found.
• Compare the inbound topic, reason, endpoint, headers, payload preference, and filter criteria with the stored record.
• Replace the full stored header map when header values change.
• Replace stored filter rows when filter criteria change.
• Notify BCBSA only when provider-originated filter criteria change.
• Trigger endpoint handshake verification only when the provider callback endpoint changes.
• Persist changes before initiating external synchronization or endpoint verification.
• Return HTTP 200 with the updated Subscription without waiting for an asynchronous endpoint handshake.
• Keep a provider subscription in requested status until the asynchronous handshake succeeds or fails.
• Treat an identical PUT as idempotent and avoid duplicate external calls when relevant data has not changed.

Query subscription status

• Accept POST /Subscription/$status with a FHIR Parameters request.
• Read the identifier from parameter[name="id"].valueId.
• Use the CareFirst Subscription ID for provider requests and the BCBSA correlation ID for BCBSA requests.
• Return a FHIR searchset Bundle with exactly one Parameters entry when found.
• Return the subscription reference, topic, current status, notification type query-status, and events-since-subscription-start value.
• Use the internal Subscription ID in a provider-facing reference and the BCBSA correlation ID in a BCBSA-facing reference.
• Include one or more error parameters when the stored status is error.
• Perform no data modification. The operation is read-only.
• Return events-since-subscription-start as 0 in the current implementation because event counting is not yet implemented.

Delete a subscription

• Accept DELETE /Subscription/{id} with no FHIR request body.
• Use the CareFirst Subscription ID as {id} for provider requests and the BCBSA correlation ID for BCBSA requests.
• Retrieve the existing Subscription before deactivation.
• Soft-delete the record by setting status to off; retain subscription and filter records for audit.
• For provider-originated deletes, attempt BCBSA deregistration using the stored BCBSA correlation ID after local deactivation succeeds.
• For BCBSA-originated deletes, perform local deactivation only and do not call BCBSA back.
• Return HTTP 200 if the provider-side local deactivation succeeds, even if the subsequent BCBSA deregistration fails. The BCBSA failure is logged for operational review.
• Return HTTP 200 without further calls when the subscription is already off.

Receive handshake notifications

• Receive a Bundle of type history.
• Read the Parameters resource in the first Bundle entry.
• Verify that type is handshake.
• Read the Subscription and topic references.
• Return a successful 2xx acknowledgement to confirm endpoint reachability.
• Do not expect a PAS ClaimResponse focus Bundle in a handshake notification.

Receive event notifications

• Receive a Bundle of type history containing:
  • A Parameters resource describing the event.
  • A PAS Bundle containing ClaimResponse and supporting resources.
• Read the Subscription reference and PAS topic.
• Verify that status is active and type is event-notification.
• Read the event number, timestamp, and focus reference.
• Resolve the focus reference to the PAS Bundle entry.
• Process the ClaimResponse and supporting Patient, Coverage, Organization, Practitioner, and other included resources.
• Return a successful 2xx acknowledgement after accepting the message.

Notification matching and delivery behavior

• Consider only active subscriptions for event delivery.
• Match organization identifiers using the registered NPI or Tax ID filters.
• Treat either a matching NPI or matching Tax ID as sufficient under the current matching design.
• Deliver independently to every active subscription that matches.
• Use provider identifier enrichment when an applicable requestor resource does not contain all identifiers needed for matching.
• Record every inbound event in the CareFirst notification audit flow.
• Track delivery outcomes such as pending, delivered, failed, unmatched, and enrichment_failed.

Illustrative HTTP requests

POST /Subscription HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

PUT /Subscription/{id} HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

POST /Subscription/$status HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Content-Type: application/fhir+json
Accept: application/fhir+json

DELETE /Subscription/{id} HTTP/1.1
Host: {carefirst-api-host}
Authorization: Bearer {access-token}
x-api-key: {assigned-api-key}
Accept: application/fhir+json

The provider callback must accept:

POST /$notification-hook HTTP/1.1
Host: {registered-provider-host}
Content-Type: application/fhir+json

Illustrative status request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "id",
      "valueId": "11111111-2222-3333-4444-555555555555"
    }
  ]
}

Illustrative status response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "timestamp": "2026-09-25T18:15:00Z",
  "total": 1,
  "entry": [
    {
      "fullUrl": "urn:uuid:status-parameters-1",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "subscription",
            "valueReference": {
              "reference": "Subscription/11111111-2222-3333-4444-555555555555"
            }
          },
          {
            "name": "topic",
            "valueCanonical": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic"
          },
          {
            "name": "status",
            "valueCode": "active"
          },
          {
            "name": "type",
            "valueCode": "query-status"
          },
          {
            "name": "events-since-subscription-start",
            "valueString": "0"
          }
        ]
      }
    }
  ]
}

Illustrative handshake notification

{
  "resourceType": "Bundle",
  "type": "history",
  "timestamp": "2026-09-25T18:00:00Z",
  "entry": [
    {
      "fullUrl": "urn:uuid:parameters-1",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "subscription",
            "valueReference": {
              "reference": "Subscription/11111111-2222-3333-4444-555555555555"
            }
          },
          {
            "name": "topic",
            "valueCanonical": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic"
          },
          {
            "name": "status",
            "valueCode": "requested"
          },
          {
            "name": "type",
            "valueCode": "handshake"
          },
          {
            "name": "events-since-subscription-start",
            "valueString": "0"
          }
        ]
      }
    }
  ]
}

Illustrative event notification

{
  "resourceType": "Bundle",
  "id": "notification-1",
  "type": "history",
  "timestamp": "2026-09-25T18:30:00Z",
  "entry": [
    {
      "fullUrl": "urn:uuid:event-parameters-1",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "subscription",
            "valueReference": {
              "reference": "Subscription/11111111-2222-3333-4444-555555555555"
            }
          },
          {
            "name": "topic",
            "valueCanonical": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic"
          },
          {
            "name": "status",
            "valueCode": "active"
          },
          {
            "name": "type",
            "valueCode": "event-notification"
          },
          {
            "name": "notification-event",
            "part": [
              {
                "name": "event-number",
                "valueString": "1"
              },
              {
                "name": "timestamp",
                "valueInstant": "2026-09-25T18:30:00Z"
              },
              {
                "name": "focus",
                "valueReference": {
                  "reference": "urn:uuid:pas-bundle-1"
                }
              }
            ]
          }
        ]
      }
    },
    {
      "fullUrl": "urn:uuid:pas-bundle-1",
      "resource": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "ClaimResponse",
              "status": "active",
              "use": "preauthorization",
              "outcome": "complete"
            }
          }
        ]
      }
    }
  ]
}

5 Limitations

• The API supports PAS prior authorization subscription events and is not a general-purpose FHIR event broker.
• Only subscriptions with status active are eligible for event delivery.
• A create request does not preserve a caller-assigned Subscription ID. CareFirst generates the authoritative ID.
• A provider-originated subscription can remain requested until callback endpoint verification completes.
• On update, filter synchronization and endpoint verification are independent. Both can be triggered by one PUT.
• A provider endpoint change is verified asynchronously after the update response is returned.
• The full callback header map is replaced when headers change. Partial header patch semantics are not supported.
• The inter-plan update result may not be exposed in the provider-facing Subscription response.
• $status currently reports events-since-subscription-start as 0; event counting is not implemented.
• Delete is a soft delete only. CareFirst does not physically remove subscription or filter records.
• A provider delete can return HTTP 200 even when BCBSA deregistration fails after local deactivation. The subscription remains off locally and the external failure requires operational follow-up.
• $status returns exactly one searchset entry for a found subscription and returns HTTP 404 when no matching subscription exists.
• A notification can match more than one active subscription and can be delivered to multiple endpoints.
• Notification delivery can be duplicated or delayed. Consumers must implement idempotency.
• Event sequence tracking and replay behavior are release specific. Consumers must not depend solely on events-since-subscription-start.
• Final retry policies for some inter-plan and callback-delivery failures are release specific.
• Provider identifier enrichment failure can prevent delivery even when an event was accepted by CareFirst.
• The registered callback endpoint must remain reachable and must continue to meet CareFirst connectivity requirements.
• The callback acknowledgment does not indicate that the contained prior authorization was approved.
• Endpoint URLs, scopes, required headers, timeouts, retry counts, volume limits, and service levels vary by environment and release.

6 Typical Interaction

Subscription create workflow

1. The provider registers its application and callback endpoint with CareFirst.
2. The provider sends POST /Subscription with the PAS topic, organization filter, endpoint, payload preference, and applicable headers.
3. CareFirst validates the Subscription and callback URL.
4. CareFirst generates the Subscription GUID and persists the subscription with status requested.
5. CareFirst performs applicable inter-plan registration for a provider-originated request.
6. CareFirst sends a handshake Bundle to the stored callback endpoint.
7. The provider validates and acknowledges the handshake.
8. CareFirst changes the subscription to active after success, or to error after failure.
9. CareFirst returns or maintains the resulting subscription lifecycle state according to the create contract.

Subscription update workflow

1. The provider sends PUT /Subscription/{id} with the complete updated Subscription.
2. CareFirst validates the filter and endpoint.
3. CareFirst retrieves the existing record.
4. CareFirst compares filters, callback endpoint, headers, topic, reason, and payload preference.
5. CareFirst persists the changed fields first.
6. If filters changed, CareFirst synchronizes the change with the applicable inter-plan route.
7. If the endpoint changed, CareFirst resets status to requested and starts an asynchronous handshake.
8. CareFirst returns HTTP 200 without waiting for the asynchronous handshake.
9. The background handshake result changes status to active or error.

Subscription status workflow

1. The consumer sends POST /Subscription/$status with a FHIR Parameters body.
2. CareFirst extracts parameter[name="id"].valueId and determines the caller source.
3. CareFirst looks up the record by internal Subscription ID for a provider or BCBSA correlation ID for BCBSA.
4. CareFirst builds a searchset Bundle containing one Parameters resource.
5. CareFirst returns the subscription reference, topic, current status, query-status type, and event count.
6. If status is error, CareFirst also returns stored error code and description parameters.
7. No subscription data is changed.

Subscription delete workflow

1. The consumer sends DELETE /Subscription/{id}.
2. CareFirst validates the source-specific identifier and retrieves the subscription.
3. If the record is already off, CareFirst returns HTTP 200 without additional calls.
4. CareFirst soft-deletes the local record by setting status to off.
5. For a provider-originated delete, CareFirst attempts BCBSA deregistration using the stored BCBSA correlation ID.
6. For a BCBSA-originated delete, CareFirst does not make an outbound BCBSA call.
7. CareFirst returns HTTP 200 after successful local deactivation. A later BCBSA failure is logged and does not roll back the local deactivation.

Prior authorization notification workflow

1. A prior authorization status event is generated by CareFirst, a delegated vendor, or BCBSA.
2. CareFirst receives and records the event and acknowledges the source.
3. CareFirst verifies that the event is part of the applicable PAS workflow.
4. CareFirst identifies the requestor Organization or PractitionerRole.
5. CareFirst extracts or enriches NPI and Tax ID.
6. CareFirst finds every active Subscription whose filter matches either identifier.
7. CareFirst constructs a history Bundle containing event Parameters and the PAS focus Bundle.
8. CareFirst sends the Bundle to each matching endpoint.
9. The provider durably accepts the event and returns a 2xx response.
10. CareFirst records delivery as delivered, failed, unmatched, or enrichment failed.

POST /Subscription
  -> Validate Subscription and endpoint
  -> Generate CareFirst Subscription ID
  -> Persist status=requested and filters
  -> Perform applicable inter-plan registration
  -> Send handshake
  -> Set status=active or error

PUT /Subscription/{id}
  -> Validate full updated Subscription
  -> Retrieve existing record
  -> Detect filter and endpoint changes
  -> Persist updates
  -> Sync changed filters when applicable
  -> Verify changed endpoint asynchronously
  -> Return updated Subscription

POST /Subscription/$status
  -> Validate Parameters ID
  -> Retrieve by Subscription ID or BCBSA correlation ID
  -> Build one-entry searchset Bundle
  -> Return lifecycle status and error details when applicable

DELETE /Subscription/{id}
  -> Validate source-specific ID
  -> Retrieve existing subscription
  -> Soft-delete locally by setting status=off
  -> Provider source: attempt BCBSA deregistration
  -> Return HTTP 200 after local success

Prior authorization event
  -> Audit and acknowledge source
  -> Resolve requestor identifiers
  -> Match active subscriptions
  -> Build PAS event-notification Bundle
  -> Deliver to all matched endpoints
  -> Record delivery outcome

7 Core Schema Elements

Subscription management

Status request and response

Delete request

Handshake and event notification

Filter and delivery interpretation

• Register one or more organization identifiers using the CareFirst-supported filter syntax.
• A subscription can contain separate filters for NPI and Tax ID.
• The current matching design uses OR behavior. Either identifier can match the subscription.
• Only active subscriptions are selected for event delivery.
• More than one subscription can match the same event.
• The consumer must correlate the focus PAS Bundle using the notification-event.focus reference, not by Bundle entry order alone.
• The consumer must use the ClaimResponse to interpret the authorization outcome.

8 Validation and Error Handling

Common validation

Create validation and processing

Update validation and processing

Status validation and processing

Delete validation and processing

Provider callback handling

CareFirst event matching and delivery outcomes

Illustrative OperationOutcome

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Subscription.channel.endpoint is missing or invalid."
      }
    }
  ]
}

Consumer error-handling requirements

• Inspect both the HTTP status and returned FHIR resource.
• Retain the CareFirst Subscription ID and use it for provider-originated status checks, updates, and deletes.
• Treat $status as read-only and inspect the returned status and optional error parameters.
• Treat DELETE as deactivation. Do not assume the record was physically removed.
• A provider DELETE HTTP 200 confirms local deactivation but may not prove that BCBSA deregistration succeeded.
• Do not treat status requested as active.
• After changing the callback endpoint, expect status to remain requested until asynchronous verification completes.
• Keep a durable deduplication key using the Subscription reference, event number, and PAS transaction identifiers.
• Acknowledge valid notifications promptly after durable acceptance, then perform expensive processing asynchronously.
• Do not interpret notification delivery as authorization approval. Inspect ClaimResponse outcome and adjudication.
• Do not retry structural validation failures without correcting the request.
• Retry transient management-operation failures only when the CareFirst contract permits it.
• Do not automatically create a second subscription when a create response is uncertain. Reconcile using correlation data through the approved support process.
• Log only approved operational metadata. Do not log tokens, secrets, full notification Bundles, member identifiers, or clinical data unless explicitly permitted.