This tutorial demonstrates how an in-network provider can interact with a payer to discover coverage requirements using CDS Hooks. It covers:
To retrieve all CDS services configured by the payer that the provider can invoke for coverage rules evaluation, providers can send a GET request to the CDS Discovery endpoint:
HTTP Request:
GET [PAYER_BASE_URL]/cds-services
Authorization: Bearer <ACCESS_TOKEN>
Response The GET request returns a JSON object representing the configured CDS services for the payer. Each service includes:
order-sign, order-dispatch).{
"services": [
{
"hook": "order-sign",
"id": "prior_auth_crd_order_sign",
"title": "Order sign request",
"description": "A CDS Hook for order sign requests",
"prefetch": {
"patient": "Patient/{{context.patientId}}",
"coverageBundle": "Coverage?patient={{context.patientId}}&status=active&_include=Coverage:payor"
},
"extension": {
"davinci-crd.configuration-options": [
{
"code": "coverage-info",
"type": "boolean",
"name": "Coverage Information",
"description": "Indicates whether coverage information should be returned",
"default": true
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service",
"default": 10
}
],
"davinci-crd.version": [
"2.1"
]
}
}
]
}
The extension block in the discovery response is driven by the extension object in the configured hook JSON file. See the payer setup guide for configuration details.
After a CDS service has been identified from the discovery step, the service can be called to evaluate coverage rules for a specific context (e.g., a draft order for a patient).
HTTP Request
POST [PAYER_BASE_URL]/cds-services/{service-id}
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Request Body:
The request body contains all necessary information for the CDS service to evaluate rules. It includes:
{
"hookInstance": "12345678-1234-1234-1234-1234567890ab",
"hook": "order-sign",
"fhirServer": "{PROVIDER_FHIR_ENDPOINT}",
"fhirAuthorization": {
"access_token": "{ACCESS_TOKEN}",
"token_type": "Bearer",
"expires_in": 300,
"scope": "user/*.read",
"subject": "{CLIENT_ID}"
},
"context": {
"userId": "Practitioner/789",
"patientId": "123",
"encounterId": "456",
"draftOrders": {
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "ServiceRequest",
"id": "a1b2c3",
"status": "draft",
"intent": "order",
"subject": {
"reference": "Patient/123"
}
}
}
]
}
},
"prefetch": {
"patient": {
"resourceType": "Patient",
"id": "123"
},
"coverageBundle": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Coverage",
"id": "d4e5f6",
"status": "active",
"beneficiary": {
"reference": "Patient/123"
}
}
}
]
}
},
"extension": {
"davinci-crd.configuration": {
"max-cards": 10,
"coverage-info": true
}
}
}
Notes:
{service-id} in the URL with the id from the discovery response, and {PROVIDER_FHIR_ENDPOINT} with the provider FHIR server URL.prefetch field can include any FHIR resources the CDS service requires to evaluate rules efficiently.Response
The CDS service returns a JSON object containing “cards” that represent the evaluated coverage requirements and recommendations. Each card may include:
info, warning, critical).Sample Response:
{
"cards": [
{
"extension": {
"davinci-associated-resource": [
"ServiceRequest/5336e609-9af6-4dc6-bde3-fbb55e99f6ed"
]
},
"uuid": "9e65f759-267e-4d7c-9360-6f19a52cd8ca",
"summary": "Prior Authorization Required",
"detail": "Prior authorization is required for Multiple sleep latency or maintenance of wakefulness testing, recording, analysis and interpretation of physiological measurements of sleep during multiple trials to assess sleepiness",
"indicator": "warning",
"source": {
"label": "Health Level Seven International",
"url": "https://www.hl7.org/",
"topic": {
"code": "auth-needed",
"system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"display": "Prior Authorization Needed"
}
}
}
]
}
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.