Setup Prior Auth for Payers

Setup Prior Auth for Providers (DEMO)

This section describes the steps required to set up a DEMO provider to test your prior-auth payer setup. This configuration assumes you have set up the prior-auth as described in the payer-setup section. (See Prior Auth Payer Setup for reference.)

1. Overview

This setup will expect that you have a mock EMR and the DTR app available. The mock EMR is not included in the Smile solution and needs to be provided by the implementor. The instructions below are based upon the behavior of our mock-EMR but might differ per provider implementation.

additional module configurations to mimic the provider side of the solution.
security and user permissions to allow access for the client apps (mock EMR and DTR app).

2. Setting up a demo provider environment

The CRD request is a CDS hooks request. A provider FHIR repository and persistence is required to perform the CRD request. This FHIR repository will act as the provider's prefetch server and store the Patient data related to the request.

2.1 Module requirements

Provider persistence module
Provider FHIR R4 endpoint
Persistence module supporting the DTR SoF app
FHIR R4 endpoint supporting the DTR SoF app
CQL module for SoF FHIR endpoint to register the $populate operation
DTR module for SoF FHIR endpoint to register the $populate operation

2.2 Configuration example

# provider persistence
module.persistence_provider.type=PERSISTENCE_R4

# provider endpoint
module.fhir_endpoint_provider.type=ENDPOINT_FHIR_REST
module.fhir_endpoint_provider.requires.PERSISTENCE_ALL=persistence_provider
module.fhir_endpoint_provider.requires.SECURITY_IN_UP=local_security
module.fhir_endpoint_provider.requires.SECURITY_IN_OIC=smart_auth
module.fhir_endpoint_provider.config.security.oic.enabled=true

# DTR SoF persistence
module.persistence_sof.type=PERSISTENCE_R4

# DTR SoF endpoint
module.fhir_endpoint_sof.type=ENDPOINT_FHIR_REST
module.fhir_endpoint_sof.requires.PERSISTENCE_ALL=persistence_sof
module.fhir_endpoint_sof.requires.SECURITY_IN_UP=local_security
module.fhir_endpoint_sof.requires.SECURITY_IN_OIC=smart_auth
module.fhir_endpoint_sof.config.security.oic.enabled=true

# cql module for SOF to enable $populate operation
module.cql_sof.type=CQL
module.cql_sof.requires.ENDPOINT_FHIR=fhir_endpoint_sof

# DTR module for SOF to enable $populate operation
module.dtr_sof.type=PRIOR_AUTH_DTR
module.dtr_sof.requires.CQL=cql_sof
module.dtr_sof.requires.ENDPOINT_FHIR=fhir_endpoint_sof

2.3 Configure the Outbound Security Module (for DTR app Launch)

The DTR app requires a session with the following properties. The snippet below is an example of the fields to be populated in the onTokenGenerating callback script.

function onTokenGenerating(theUserSession, theAuthorizationRequestDetails) {
   // parse launch parameters from SoF app's launch URL and add to FHIR context
   const regex = /([a-zA-Z]+\/[^"]+)/g;
   theAuthorizationRequestDetails.launch
    ?.match(regex)
    .forEach((resource) => theUserSession.addFhirContextReference(resource));
   
   const patientId = theAuthorizationRequestDetails.launch
    ?.split("Patient/")[1]
    .split('"')[0];
   if (patientId) {
      theUserSession.addLaunchResourceId("Patient", patientId);
   }

   // Set fhirUser to the provider's PractitionerRole
   theUserSession.setFhirUserUrl('PractitionerRole/provider-practitioner-role-1');
}

2.3 User Permissions

The permissions outlined below show what permissions are required for a user to perform operations to complete the prior-auth steps CRD, DTR and PAS. The permissions are split per repository and assumes the mock-EMR to update the order after the CRD response and use $populate to pre-populate the Questionnaire form.

2.3.1 User Permissions on the payer repository

Permission	Arguments	Description
`INVOKE_CDS_HOOKS`		CRD operation permission
`FHIR_EXTENDED_OPERATION_ON_TYPE`	Questionnaire/$questionnaire-package Questionnaire/$next-question Questionnaire/$log-questionnaire-errors	DTR operation permissions
`FHIR_EXTENDED_OPERATION_ON_TYPE`	Claim/$submit Claim/$inquire	PAS operation permissions
`SUBMIT_ATTACHMENT`		PAS CDEX permission

2.3.2 User Permissions for the mock-EMR on the provider repository (DEMO repository)

Permission	Arguments	Description
`FHIR_WRITE_ALL_OF_TYPE`	ServiceRequest, DeviceRequest, NutritionOrder, MedicationRequest, CommunicationRequest	To update the order on the provider repo after prefetch.
`FHIR_WRITE_ALL_OF_TYPE`	QuestionnaireResponse, DocumentReference, Claim	For filling up the questionnaire on the DTR app
`FHIR_DELETE_ALL_OF_TYPE`	DocumentReference, Claim	For filling up the questionnaire on the DTR app
`FHIR_OP_BINARY_ACCESS_WRITE`		To support file uploads within the DTR app

2.3.3 User Permissions for DTR-app on the DTR SoF repository

Permission	Arguments	Description
`FHIR_OP_POPULATE`		To perform the `$populate` operation
`FHIR_TRANSACTION`		To store the DTRBundle which has type transaction
`FHIR_WRITE_ALL_OF_TYPE`	Bundle, Questionnaire, QuestionnaireResponse	To store the DTRBundle before performing `$populate`. More permissions might be required depending on the content of the DTRBundle

2.4 OIDC clients

Follow the below settings for OIDC client configuration:

{
   "moduleId": "smart_auth",
   "clientId": "mock-emr",
   "clientName": "mock-emr",
   "allowedGrantTypes": ["AUTHORIZATION_CODE", "REFRESH_TOKEN", "PASSWORD"],
   "autoGrantScopes": [
     "cdr_all_user_authorities",
     "launch/practitioner",
     "openid",
     "patient/*.read",
     "patient/*.write",
     "profile"
   ],
   "registeredRedirectUris": [
     "https://mock-emr"
   ],
   "scopes": [
     "launch/practitioner",
     "openid",
     "patient/*.read",
     "patient/*.write",
     "profile"
   ]
 },
 {
   "nodeId": "Master",
   "moduleId": "smart_auth",
   "clientId": "dtr",
   "clientName": "dtr app",
   "enabled": true,
   "allowedGrantTypes": ["AUTHORIZATION_CODE", "PASSWORD"],
   "autoGrantScopes": ["cdr_all_user_authorities"],
   "registeredRedirectUris": [
     "http://dtr-app"
   ],
   "scopes": [
     "fhirUser",
     "launch",
     "launch/patient",
     "launch/practitioner",
     "online_access",
     "openid",
     "patient/*.read",
     "patient/DocumentReference.write",
     "patient/QuestionnaireResponse.write",
     "user/*.read"
   ]
 }

2.5 Configuring the mock-EMR and DTR app Endpoint configuration

The DTR SoF app uses Endpoint resources to determine which endpoints to use based on the Organization that was part of the launch context.

Ensure the FHIR repository contains the necessary Organization resources for each relevant payer with the following identifier:
```
{
  "system": "http://smiledigitalhealth.com/pa-org-identifier",
  "value": "<payer-org-id>"
}
```
Each organization should also contain references to Endpoint resources that reference payer services used by the DTR app. The identifier must include the system http://smiledigitalhealth.com/pa-org-endpoint, and the value must be set exactly as one of the following, according to the corresponding service:
- CDEXAttachment – Handles attachment submissions to the payer
- CDSDiscovery – Provides the CDS Hooks discovery endpoint for order-sign requests
- DTRQuestionnairePackage – Retrieves the payer’s Questionnaire package for prior authorization
- DTRNextQuestion – For retrieving next section of adaptive questionnaires for prior authorization
- DTRQuestionnaireError – Receives error information related to Questionnaire processing
- PASSubmit – Submits prior authorization requests to the payer
- PASUpdate – Updates submitted prior authorization requests
- PASInquiry – Queries the status of prior authorization requests
These identifiers correspond to specific payer services and must be configured exactly as shown for the DTR app to function correctly.
```
 "endpoint": [
   {
     "type": "Endpoint",
     "reference": "Endpoint/CDSDiscovery",
     "identifier":  {
       "system": "http://smiledigitalhealth.com/pa-org-endpoint",
       "value":  "CDSDiscovery"
     }
   },
   ...
  ]
```

The Endpoint resources referenced by the Organization resources contain the actual URLs that the DTR app would send requests to.

{
   "resourceType": "Endpoint",
   "id": "CDSDiscovery",
   "identifier": [
      {
         "system": "http://smiledigitalhealth.com/pa-org-endpoint",
         "value": "CDSDiscovery"
      }
   ],
   "status": "active",
   "connectionType": {
      "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
      "code": "hl7-fhir-rest"
   },
   "name": "CDSDiscovery",
   "payloadType": [
      {
         "coding": [
            {
               "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
               "code": "any"
            }
         ]
      }
   ],
   "address": "${CDR_ENDPOINT}/cds-services"
}

3. Client flow

3.1 CRD

In order to determine the hook URL a discovery call has to be initiated first. The discovery endpoint is accessible from the CDS hooks module and is exposed on http://<cdshooks-base-url>/cds-services.

The response looks like this:

{
  "services": [
    {
      "hook": "order-sign",
      "title": "Order sign request",
      "description": "A CDS Hook for order sign requests",
      "id": "prior_auth_crd_order_sign",
      "prefetch": {
        "serviceRequestBundle": "ServiceRequest?_id={{context.draftOrders.ServiceRequest.id}}&_include=ServiceRequest:performer&_include=ServiceRequest:requester&_include:iterate=PractitionerRole:practitioner&_include:iterate=PractitionerRole:organization&_include:iterate=PractitionerRole:location",
        "patient": "Patient/{{context.patientId}}",
        "coverageBundle": "Coverage?patient={{context.patientId}}&status=active&_include=Coverage:payor"
      }
    }
  ]
}

The client can use the ID to send a CRD request. The URL to use will be the discovery + the hook ID eg: http://<cdshooks-base-url>/cds-services/<hook-id>.

The response to the CRD call would indicate whether prior authorization is needed or not, and other information necessary for the next steps, such as the canonical URL of the Questionnaire to be displayed on the DTR app.

3.2 DTR

The DTR (Documentation Templates and Rules) flow involves two main operations:

Retrieve Questionnaire Package from Payer – The DTR app calls the payer's $questionnaire-package operation to get the documentation templates.
Pre-populate the Questionnaire – The DTR app calls the $populate operation on the DTR SoF endpoint to auto-fill patient data into the Questionnaire.

3.2.1 Retrieve the Questionnaire Package

The DTR app retrieves the payer's structured documentation templates using the $questionnaire-package operation.

Endpoint: POST [PAYER_BASE_URL]/Questionnaire/$questionnaire-package

Example Request:

POST /payer-fhir/Questionnaire/$questionnaire-package
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json

Request Body (Parameters resource):

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaire",
      "valueCanonical": "http://example.org/fhir/Questionnaire/pa-questionnaire-1"
    },
    {
      "name": "coverage",
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-1",
        "status": "active",
        "beneficiary": { "reference": "Patient/patient-1" },
        "payor": [{ "reference": "Organization/payer-org-1" }]
      }
    },
    {
      "name": "order",
      "resource": {
        "resourceType": "ServiceRequest",
        "id": "service-request-1",
        "status": "draft",
        "intent": "order",
        "subject": { "reference": "Patient/patient-1" }
      }
    }
  ]
}

Example Response:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "PackageBundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "Questionnaire",
              "id": "pa-questionnaire-1",
              "url": "http://example.org/fhir/Questionnaire/pa-questionnaire-1",
              "status": "active",
              "title": "Prior Authorization Questionnaire",
              "item": [
                { "linkId": "1", "text": "Patient Name", "type": "string" },
                { "linkId": "2", "text": "Service Date", "type": "date" }
              ]
            }
          },
          {
            "resource": {
              "resourceType": "Library",
              "id": "pa-cql-library",
              "url": "http://example.org/fhir/Library/pa-cql-library",
              "status": "active"
            }
          }
        ]
      }
    }
  ]
}

3.2.2 Pre-populate the Questionnaire

After retrieving the Questionnaire package, the DTR app calls the $populate operation on the DTR SoF endpoint to auto-fill patient data.

Endpoint: POST [SOF_FHIR_BASE_URL]/Questionnaire/$populate

Example Request:

POST /sof-fhir/Questionnaire/$populate
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json

Request Body (Parameters resource):

{
   "resourceType": "Parameters",
   "parameter": [
      {
         "name": "canonical",
         "valueString": "http://example.org/fhir/Questionnaire/pa-questionnaire-1"
      },
      {
         "name": "subject",
         "valueReference": { "reference": "Patient/patient-1" }
      },
      {
         "name": "parameters",
         "resource": {
            "resourceType": "Parameters",
            "parameter": [
               {
                  "name": "Service Request Id",
                  "valueString": "service-request-1"
               },
               {
                  "name": "Coverage Id",
                  "valueString": "Coverage/coverage-1"
               }
            ]
         }
      }
   ]
}

Example Response (QuestionnaireResponse):

{
  "resourceType": "QuestionnaireResponse",
  "questionnaire": "http://example.org/fhir/Questionnaire/pa-questionnaire-1",
  "status": "in-progress",
  "subject": { "reference": "Patient/patient-1" },
  "item": [
    {
      "linkId": "1",
      "text": "Patient Name",
      "answer": [{ "valueString": "John Doe" }]
    },
    {
      "linkId": "2",
      "text": "Service Date"
    }
  ]
}

3.3 PAS

The PAS (Prior Authorization Support) flow submits and tracks prior authorization requests to the payer.

Submit a Prior Authorization Request – The client calls Claim/$submit on the payer endpoint.
Check the Status of a Prior Authorization – The client calls Claim/$inquire on the payer endpoint.

3.3.1 Submit a Prior Authorization Request

After completing the DTR questionnaire, the client submits a prior authorization request using the Claim/$submit operation.

Endpoint: POST [PAYER_BASE_URL]/Claim/$submit

Example Request:

POST /payer-fhir/Claim/$submit
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json

Request Body (PAS Request Bundle):

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Claim",
        "id": "pa-claim-1",
        "status": "active",
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",
            "code": "professional"
          }]
        },
        "use": "preauthorization",
        "patient": { "reference": "Patient/patient-1" },
        "created": "2025-01-15",
        "provider": { "reference": "Organization/provider-org-1" },
        "insurer": { "reference": "Organization/payer-org-1" },
        "priority": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/processpriority",
            "code": "normal"
          }]
        },
        "insurance": [{
          "sequence": 1,
          "focal": true,
          "coverage": { "reference": "Coverage/coverage-1" }
        }],
        "item": [{
          "sequence": 1,
          "productOrService": {
            "coding": [{
              "system": "http://www.ama-assn.org/go/cpt",
              "code": "95810",
              "display": "Polysomnography; sleep staging"
            }]
          }
        }],
        "supportingInfo": [{
          "sequence": 1,
          "category": {
            "coding": [{
              "system": "http://hl7.org/fhir/us/davinci-pas/CodeSystem/PASSupportingInfoType",
              "code": "questionnaire"
            }]
          },
          "valueReference": { "reference": "QuestionnaireResponse/qr-1" }
        }]
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "id": "patient-1",
        "name": [{ "family": "Doe", "given": ["John"] }]
      }
    },
    {
      "resource": {
        "resourceType": "Coverage",
        "id": "coverage-1",
        "status": "active",
        "beneficiary": { "reference": "Patient/patient-1" },
        "payor": [{ "reference": "Organization/payer-org-1" }]
      }
    }
  ]
}

Example Response (PAS Response Bundle):

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "ClaimResponse",
        "id": "pa-response-1",
        "status": "active",
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",
            "code": "professional"
          }]
        },
        "use": "preauthorization",
        "patient": { "reference": "Patient/patient-1" },
        "created": "2025-01-15T10:00:00Z",
        "insurer": { "reference": "Organization/payer-org-1" },
        "request": { "reference": "Claim/pa-claim-1" },
        "outcome": "queued",
        "item": [{
          "itemSequence": 1,
          "adjudication": [{
            "category": {
              "coding": [{
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "submitted"
              }]
            }
          }],
          "extension": [{
            "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewAction",
            "extension": [{
              "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewActionCode",
              "valueCodeableConcept": {
                "coding": [{
                  "system": "http://hl7.org/fhir/us/davinci-pas/CodeSystem/PASSupportingInfoType",
                  "code": "pended",
                  "display": "Pended"
                }]
              }
            }]
          }]
        }]
      }
    }
  ]
}

3.3.2 Check the Status of a Prior Authorization

Use the Claim/$inquire operation to check the status of a previously submitted prior authorization request.

Endpoint: POST [PAYER_BASE_URL]/Claim/$inquire

Example Request:

POST /payer-fhir/Claim/$inquire
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json

Request Body (PAS Inquiry Request Bundle):

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Claim",
        "id": "pa-inquiry-1",
        "status": "active",
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",
            "code": "professional"
          }]
        },
        "use": "preauthorization",
        "patient": { "reference": "Patient/patient-1" },
        "created": "2025-01-15",
        "provider": { "reference": "Organization/provider-org-1" },
        "insurer": { "reference": "Organization/payer-org-1" },
        "priority": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/processpriority",
            "code": "normal"
          }]
        },
        "insurance": [{
          "sequence": 1,
          "focal": true,
          "coverage": { "reference": "Coverage/coverage-1" }
        }],
        "extension": [{
          "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-identifierReference",
          "valueReference": { "reference": "ClaimResponse/pa-response-1" }
        }]
      }
    }
  ]
}

Example Response (PAS Inquiry Response Bundle):

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "ClaimResponse",
        "id": "pa-response-1",
        "status": "active",
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",
            "code": "professional"
          }]
        },
        "use": "preauthorization",
        "patient": { "reference": "Patient/patient-1" },
        "created": "2025-01-15T12:00:00Z",
        "insurer": { "reference": "Organization/payer-org-1" },
        "request": { "reference": "Claim/pa-claim-1" },
        "outcome": "complete",
        "item": [{
          "itemSequence": 1,
          "adjudication": [{
            "category": {
              "coding": [{
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "submitted"
              }]
            }
          }],
          "extension": [{
            "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewAction",
            "extension": [{
              "url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewActionCode",
              "valueCodeableConcept": {
                "coding": [{
                  "system": "https://codesystem.x12.org/005010/306",
                  "code": "A1",
                  "display": "Certified in total"
                }]
              }
            }]
          }]
        }]
      }
    }
  ]
}

Setup Prior Auth for Payers