CRD Service REST API Specification
Overview
As part of the InterSystems® Payer Services CRD (Coverage Requirements Discovery) REST APIs, a provider’s client application can invoke one of the available CDS services by sending a request to the relevant endpoint for that service. They can submit a CRD query to a CRD service’s service endpoint to find out the payer’s coverage requirements for a given service or device.
Refer to the audience and connection sections of the Using the Public APIs guide for general information on prerequisites, connectivity, and authentication. To use these REST APIs, you will also need to know the base URL of the payer server that you will be connecting to. In addition, you will need information about the desired CRD service or services which can be retrieved from the discovery API response. This will provide the unique identifier for the service and the appropriate point in the provider workflow (the hookOpens in a new tab) when the service should be invoked.
The CRD APIs are designed in compliance with the CMS-0057-F regulationsOpens in a new tab and the CDS Hooks SpecificationOpens in a new tab.
Workflow
A typical CRD workflow including use of the service API is as follows:
-
A provider’s client application sends a request to the discovery endpoint of the CDS Hooks server of their patient’s payer to receive information about the services that are available at that server. This includes the HL7® FHIR® resources required by each service.
-
The client invokes one of the available services by sending a request to the payer’s relevant service endpoint (this API) at the appropriate point in the provider workflow (the hookOpens in a new tab). This request provides access to any FHIR resources that the service requires to perform its evaluation. The server responds to a valid service call with the appropriate cards or system actions, if any.
-
Optionally, the client sends information about the end user’s response to a service’s card to the feedback endpoint for the service previously called.
Endpoint: cds-services/<id>
URL
The URL for this API is:
<BaseURL>/csp/healthshare/<namespace_identifier>/cds-hooks/r4/cds-services/<serviceID>
where <BaseURL> and <namespace_identifier> have been provided to you by the payer organization you are connecting with, and <serviceID> is the identifier for the required service.
Optional Capabilities
None.
Endpoint Prerequisites
-
You have already called the discovery endpoint to identify the supported services and any corresponding prefetch requirements.
Required Header Settings
-
Content-Type: application/json
-
Accept: application/json
Request Methods
POST <BaseURL>/csp/healthshare/<namespace_identifier>/cds-hooks/r4/cds-services/<serviceID>
Invokes the service specified by the <serviceID> and requests a CDS service responseOpens in a new tab from your payer’s system.
Query Parameters
None.
Request Body
The body of the request is a CDS service requestOpens in a new tab. Each service request may require FHIR resource data about the patient or the clinical context to perform a meaningful evaluation. (The discovery response also specifies the data required by each available service.) You must provide access to this data in the body of the service request using one of the following methods:
-
Fetch the data prior to sending the service request, and then pass along the prefetch data within the request body.
-
Acquire an OAuth 2.0 access token from the FHIR repository’s authorization server, which will allow the payer system to query the FHIR repository directly for the data it requires. Include the access token along with other FHIR resource access parametersOpens in a new tab in the request body.
-
Combine the two preceding methods: provide some prefetch data in the request body along with FHIR resource access parameters, enabling the payer system to acquire the rest of the required data.
An example request body is as follows:
{
"hookInstance": "1372e258-5ae2-4dd3-b716-dd0b1e7a8728",
"fhirServer": "http://example.org/some-payer/fhir/crd",
"hook": "order-sign",
"fhirAuthorization": {
"access_token": "some-opaque-fhir-access-token",
"token_type": "Bearer",
"expires_in": 300,
"scope": "user/Patient.read user/Observation.read",
"subject": "cds-service4"
},
"context": {
"userId": "Practitioner/ABC",
"patientId": "123",
"encounterId": "987",
"draftOrders": {
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/MedicationRequest/1111",
"resource": {
"resourceType": "MedicationRequest",
"id": "1111",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Diclofenac potassium 50 MG Oral Tablet prescription for Amy V. Baxter by Dr. Jones, Feb 15, 2019<br/>1 50mg tablet, 3 times per day<br/>Dispense 90 tablets, 5 refills</div>"
},
"status": "draft",
"intent": "order",
"medicationReference": {
"reference": "http://example.org/someEHR/fhir/Patient/MED1"
},
"subject": {
"reference": "http://example.org/someEHR/fhir/Patient/123"
},
"encounter": {
"reference": "http://example.org/someEHR/fhir/Encounter/987"
},
"authoredOn": "2015-11-01",
"requester": {
"reference": "http://example.org/someEHR/fhir/PractitionerRole/ABC"
},
"dosageInstruction": [
{
"text": "1 50mg tablet, 3 times per day",
"timing": {
"repeat": {
"boundsPeriod": {
"start": "2015-11-01",
"end": "2016-05-01"
},
"frequency": 3,
"period": 1,
"periodUnit": "d"
}
},
"doseAndRate": [
{
"doseQuantity": {
"value": 1,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
]
}
],
"dispenseRequest": {
"numberOfRepeatsAllowed": 5,
"quantity": {
"value": 90,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
},
{
"fullUrl": "http://example.org/someEHR/fhir/MedicationRequest/2222",
"resource": {
"resourceType": "MedicationRequest",
"id": "2222",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"<Abuse-Deterrent 12 HR oxycodone hydrochloride 10 MG Extended Release Oral Tablet [Oxycontin] prescription for Amy V. Baxter by Dr. Jones, Feb 15, 2019<br/>1 10mg tablet, every 12 hours<br/>Dispense 28 tablets, 0 refills</div>"
},
"status": "draft",
"intent": "order",
"medicationReference": {
"reference": "http://example.org/someEHR/fhir/Patient/MED2"
},
"subject": {
"reference": "http://example.org/someEHR/fhir/Patient/123"
},
"encounter": {
"reference": "http://example.org/someEHR/fhir/Encounter/987"
},
"authoredOn": "2015-11-01",
"requester": {
"reference": "http://example.org/someEHR/fhir/PractitionerRole/ABC"
},
"dosageInstruction": [
{
"text": "1 10mg tablet, every 12 hours",
"timing": {
"repeat": {
"boundsPeriod": {
"start": "2015-11-01",
"end": "2015-11-15"
},
"frequency": 1,
"period": 12,
"periodUnit": "h"
}
},
"doseAndRate": [
{
"doseQuantity": {
"value": 1,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
]
}
],
"dispenseRequest": {
"numberOfRepeatsAllowed": 0,
"quantity": {
"value": 28,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
}
]
}
},
"prefetch": {
"patient": {
"resourceType": "Patient",
"id": "123",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p style=\"border: 1px #661aff solid; background-color: #e6e6ff; padding: 10px;\"><b>Amy V. Baxter </b> female, DoB: 1987-02-20 ( Medical Record Number: 1032702 (use: USUAL))</p><hr/><table class=\"grid\"><tr><td style=\"background-color: #f3f5da\" title=\"Record is active\">Active:</td><td colspan=\"3\">true</td></tr><tr><td style=\"background-color: #f3f5da\" title=\"Alternate names (see the one above)\">Alt. Name:</td><td colspan=\"3\">Amy V. Shaw (OLD)</td></tr><tr><td style=\"background-color: #f3f5da\" title=\"Ways to contact the Patient\">Contact Details:</td><td colspan=\"3\"><ul><li>ph: 555-555-5555(HOME)</li><li><a href=\"mailto:amy.shaw@example.com\">amy.shaw@example.com</a></li><li>49 MEADOW ST MOUNDS OK 74047 US (OLD)</li><li>183 MOUNTAIN VIEW ST MOUNDS OK 74048 US </li></ul></td></tr></table></div>"
},
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "F"
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
"valueCode": "248152002"
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
"valueCodeableConcept": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-NullFlavor",
"code": "UNK",
"display": "Unknown"
}
],
"text": "Unknown"
}
}
],
"identifier": [
{
"use": "usual",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR",
"display": "Medical Record Number"
}
],
"text": "Medical Record Number"
},
"system": "http://hospital.smarthealthit.org",
"value": "1032702"
}
],
"active": true,
"name": [
{
"use": "old",
"family": "Shaw",
"given": [
"Amy",
"V."
],
"period": {
"start": "2016-12-06",
"end": "2020-07-22"
}
},
{
"family": "Baxter",
"given": [
"Amy",
"V."
],
"suffix": [
"PharmD"
],
"period": {
"start": "2020-07-22"
}
}
],
"telecom": [
{
"system": "phone",
"value": "555-555-5555",
"use": "home"
},
{
"system": "email",
"value": "amy.shaw@example.com"
}
],
"gender": "female",
"birthDate": "1987-02-20",
"address": [
{
"use": "old",
"line": [
"49 MEADOW ST"
],
"city": "MOUNDS",
"state": "OK",
"postalCode": "74047",
"country": "US",
"period": {
"start": "2016-12-06",
"end": "2020-07-22"
}
},
{
"line": [
"183 MOUNTAIN VIEW ST"
],
"city": "MOUNDS",
"state": "OK",
"postalCode": "74048",
"country": "US",
"period": {
"start": "2020-07-22"
}
}
]
},
"encounter": {
"resourceType": "Encounter",
"id": "987",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative: Encounter</b><a name=\"example-1\"> </a></p><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Resource Encounter "example-1" Updated "2017-05-26 11:56:57-0400" </p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-us-core-encounter.html\">US Core Encounter Profile (version 7.0.0-ballot)</a></p></div><p><b>status</b>: finished</p><p><b>class</b>: ambulatory (Details: http://terminology.hl7.org/CodeSystem/v3-ActCode code AMB = 'ambulatory', stated as 'ambulatory')</p><p><b>type</b>: Office Visit <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-CPT.html\">Current Procedural Terminology (CPT®)</a>#99211)</span></p><p><b>subject</b>: <a href=\"Patient-example.html\">Patient/example</a> " SHAW"</p><p><b>period</b>: 2015-11-01 17:00:14-0500 --> 2015-11-01 18:00:14-0500</p><h3>Locations</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Location</b></td></tr><tr><td style=\"display: none\">*</td><td><a href=\"Location-hospital.html\">Location/hospital: Holy Family Hospital</a> "Holy Family Hospital"</td></tr></table></div>"
},
"status": "finished",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "ambulatory"
},
"type": [
{
"coding": [
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "99211"
}
],
"text": "Office Visit"
}
],
"subject": {
"reference": "http://example.org/someEHR/fhir/Patient/123"
},
"period": {
"start": "2015-11-01T17:00:14-05:00",
"end": "2015-11-01T18:00:14-05:00"
},
"location": [
{
"location": {
"reference": "http://example.org/someEHR/fhir/Location/hospital",
"display": "Holy Family Hospital"
}
}
]
},
"coverage": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/Coverage?patient=123&status;=active"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/Coverage/COV1",
"resource": {
"resourceType": "Coverage",
"id": "COV1",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>identifier</b>: Member Number:\u00a088800933501</p><p><b>status</b>: active</p><p><b>type</b>: PPO <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://nahdo.org/sopt\">Source of Payment Typology</a>#3712; <a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-v3-ActCode.html\">ActCode</a>#PPO "preferred provider organization policy")</span></p><p><b>subscriberId</b>: 888009335</p><p><b>beneficiary</b>: <a href=\"Patient-example.html\">Patient/example</a> " SHAW"</p><p><b>relationship</b>: Self <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-subscriber-relationship.html\">SubscriberPolicyholder Relationship Codes</a>#self)</span></p><p><b>period</b>: 2020-01-01 --> (ongoing)</p><p><b>payor</b>: <a href=\"Organization-acme-payer.html\">Organization/acme-payer: Acme Health Plan</a> "Acme Health Plan"</p><blockquote><p><b>class</b></p><p><b>type</b>: An employee group <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-coverage-class.html\">Coverage Class Codes</a>#group "Group")</span></p><p><b>value</b>: xyz</p><p><b>name</b>: XYZ employee Group Plan</p></blockquote><blockquote><p><b>class</b></p><p><b>type</b>: A specific suite of benefits. <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-coverage-class.html\">Coverage Class Codes</a>#plan "Plan")</span></p><p><b>value</b>: gold</p><p><b>name</b>: Acme Gold Plan</p></blockquote></div>"
},
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB",
"display": "Member Number"
}
]
},
"system": "http://example.org/fhir/memberidentifier",
"value": "88800933501"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "PPO",
"display": "preferred provider organization policy"
}
],
"text": "PPO"
},
"subscriberId": "888009335",
"beneficiary": {
"reference": "http://example.org/someEHR/fhir/Patient/123"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
],
"text": "Self"
},
"period": {
"start": "2020-01-01"
},
"payor": [
{
"reference": "http://example.org/someEHR/fhir/Organization/acme-payer",
"display": "Acme Health Plan"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group",
"display": "Group"
}
],
"text": "An employee group"
},
"value": "xyz",
"name": "XYZ employee Group Plan"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "plan",
"display": "Plan"
}
],
"text": "A specific suite of benefits."
},
"value": "gold",
"name": "Acme Gold Plan"
}
]
},
"search": {
"mode": "match"
}
}
]
},
"device": null,
"medication": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/Medication?_id=MED1,MED2"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/Medication/MED1",
"resource": {
"resourceType": "Medication",
"id": "MED1",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative with Details</b></p><p><b>code</b>: Diclofenac Potassium (product)</p><p><b>status</b>: active</p></div>"
},
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "0093-0948",
"display": "Diclofenac Potassium (product)"
}
]
},
"status": "active"
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "http://example.org/someEHR/fhir/Medication/MED2",
"resource": {
"resourceType": "Medication",
"id": "MED2",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative with Details</b></p><p><b>code</b>: OxyContin (product)</p><p><b>status</b>: active</p></div>"
},
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "59011-410",
"display": "OxyContin (product)"
}
]
},
"status": "active"
},
"search": {
"mode": "match"
}
}
]
},
"practitioners": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/Practitioner?_id=DEF"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/Practitioner/DEF",
"resource": {
"resourceType": "Practitioner",
"id": "DEF",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>identifier</b>: id:\u00a0<a href=\"http://terminology.hl7.org/5.3.0/NamingSystem-npi.html\">#</a>9941339100, id:\u00a025456</p><p><b>name</b>: Ronald Bone </p><p><b>address</b>: 1003 HEALTHCARE DR AMHERST MA 01002 (WORK)</p></div>"
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9941339100"
},
{
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-jurisdiction",
"valueCodeableConcept": {
"coding": [
{
"system": "https://www.usps.com/",
"code": "MA"
}
],
"text": "Massachusetts"
}
}
],
"system": "http://www.acme.org/practitioners",
"value": "25456"
}
],
"name": [
{
"family": "Bone",
"given": [
"Ronald"
],
"prefix": [
"Dr"
]
}
],
"address": [
{
"use": "work",
"line": [
"1003 HEALTHCARE DR"
],
"city": "AMHERST",
"state": "MA",
"postalCode": "01002"
}
]
},
"search": {
"mode": "match"
}
}
]
},
"practitionerRoles": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/PractitionerRole?_id=ABC"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/PractitionerRole/ABC",
"resource": {
"resourceType": "PractitionerRole",
"id": "ABC",
"meta": {
"lastUpdated": "2016-02-29T23:52:32.387Z"
},
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">Dr. Ronald Bone, primary care physician at Acme Clinic</div>"
},
"practitioner": {
"reference": "http://example.org/someEHR/fhir/Practitioner/DEF",
"display": "Dr. Ronald Bone"
},
"organization": {
"reference": "http://example.org/someEHR/fhir/Organization/GHI",
"display": "Acme Clinic"
},
"code": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationFunction",
"code": "PCP",
"display": "primary care physician"
},
{
"system": "http://nucc.org/provider-taxonomy",
"code": "261QP2300X",
"display": "Primary Care Clinic/Center"
}
]
}
]
},
"search": {
"mode": "match"
}
}
]
},
"organizations": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/Organization?_id=GHI"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/Organization/GHI",
"resource": {
"resourceType": "Organization",
"id": "GHI",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>identifier</b>: id:\u00a0<a href=\"http://terminology.hl7.org/5.3.0/NamingSystem-npi.html\">#</a>1407071236, id:\u00a0121111111</p><p><b>active</b>: true</p><p><b>type</b>: Healthcare Provider <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/5.3.0/CodeSystem-organization-type.html\">Organization type</a>#prov)</span></p><p><b>name</b>: Acme Clinic</p><p><b>telecom</b>: ph: (+1) 734-677-7777, <a href=\"mailto:customer-service@acme-clinic.org\">customer-service@acme-clinic.org</a></p><p><b>address</b>: 3300 WASHTENAW AVE STE 227 AMHERST MA 01002 USA </p></div>"
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1407071236"
},
{
"system": "http://example.org/fhir/sid/us-tin",
"value": "121111111"
}
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "prov",
"display": "Healthcare Provider"
}
]
}
],
"name": "Acme Clinic",
"telecom": [
{
"system": "phone",
"value": "(+1) 734-677-7777"
},
{
"system": "email",
"value": "customer-service@acme-clinic.org"
}
],
"address": [
{
"line": [
"3300 WASHTENAW AVE STE 227"
],
"city": "AMHERST",
"state": "MA",
"postalCode": "01002",
"country": "USA"
}
]
},
"search": {
"mode": "match"
}
}
]
},
"locations": {
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.org/someEHR/fhir/r4/Location?_id=hospital"
}
],
"entry": [
{
"fullUrl": "http://example.org/someEHR/fhir/Location/hospital",
"resource": {
"resourceType": "Location",
"id": "hospital",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>name</b>: Acme Clinic</p><p></p><p><b>address</b>: 3300 WASHTENAW AVE STE 227 AMHERST MA 01002 USA </p></div>"
},
"address": {
"line": [
"3300 WASHTENAW AVE STE 227"
],
"city": "AMHERST",
"state": "MA",
"postalCode": "01002",
"country": "USA"
},
"managingOrganization": {
"reference": "http://example.org/someEHR/fhir/Organization/GHI"
}
},
"search": {
"mode": "include"
}
}
]
}
},
"extension": {
"davinci-crd.configuration": {
"coverage-info": false,
"cost": false,
"claim": false,
"appropriate-use": false,
"max-cards": 5
}
}
}
Success Response
Status code 200
The request was invoked successfully.
The body of the response is a CDS Hooks service responseOpens in a new tab, containing all cards or system actions which apply. If no cards or system actions apply, the body of the service response is a JSON object with an empty cards array.
An example of a returned response body is shown below:
{
"cards": [
{
"extension": {
"davinci-crd.associated-resource": [
{
"reference": "MedicationRequest/2222"
}
]
},
"uuid": "a1c2d18b-bc29-4ce9-be70-f6c26e1d78d8",
"summary": "Replace order with covered generic?",
"indicator": "info",
"source": {
"label": "Centers for Medicare & Medicaid Services",
"url": "https://cms.gov",
"topic": {
"system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"code": "therapy-alternatives-req",
"display": "Required Therapy Alternatives"
}
},
"suggestions": [
{
"label": "Change to lower price name brand (selected name brand not covered)",
"actions": [
{
"type": "delete",
"description": "Remove name-brand prescription",
"resourceId": "MedicationRequest/2222"
},
{
"type": "create",
"description": "Add lower-cost alternative",
"resource": {
"resourceType": "MedicationRequest",
"id": "1",
"status": "draft",
"intent": "original-order",
"medicationCodeableConcept": {
"coding": [
{
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "1790533",
"display": "Abuse-Deterrent 12 HR oxycodone 9 MG Extended Release Oral Capsule [Xtampza]"
}
]
},
"subject": {
"reference": "http://example.org/someEHR/fhir/Patient/123"
},
"encounter": {
"reference": "http://example.org/someEHR/fhir/Encounter/987"
},
"authoredOn": "2015-11-01",
"requester": {
"reference": "http://example.org/someEHR/fhir/PractitionerRole/123"
},
"dosageInstruction": [
{
"text": "1 10mg tablet, every 12 hours",
"timing": {
"repeat": {
"boundsPeriod": {
"start": "2015-11-01",
"end": "2015-11-15"
},
"frequency": 1,
"period": 12,
"periodUnit": "h"
}
},
"doseAndRate": [
{
"doseQuantity": {
"value": 1,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
]
}
],
"dispenseRequest": {
"numberOfRepeatsAllowed": 0,
"quantity": {
"value": 28,
"unit": "Tablet",
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
}
]
}
],
"selectionBehavior": "any"
},
{
"extension": {
"davinci-crd.associated-resource": [
{
"reference": "MedicationRequest/1111"
}
]
},
"uuid": "9cda1f90-48ce-4b1e-abc7-970c65c4bab9",
"summary": "Liver testing recommended",
"detail": "Administration of Diclofenac should be accompanied by SGPT monitoring due to potential toxicity",
"indicator": "info",
"source": {
"label": "Centers for Medicare & Medicaid Services",
"url": "https://cms.gov",
"topic": {
"system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"code": "clinical-reminder",
"display": "Clinical Reminder"
}
},
"suggestions": [
{
"label": "Add monthly AST test for 1st 3 months",
"actions": [
{
"type": "create",
"description": "Add order for AST test",
"resource": {
"resourceType": "ServiceRequest",
"id": "1",
"status": "draft",
"intent": "original-order",
"category": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "108252007",
"display": "Laboratory procedure"
}
]
}
],
"code": {
"coding": [
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "80076",
"display": "Hepatic function panel"
}
]
},
"subject": {
"reference": "http://example.org/fhir/Patient/123",
"display": "Jane Smith"
},
"encounter": {
"reference": "http://example.org/fhir/Encounter/ABC"
},
"occurrenceTiming": {
"repeat": {
"boundsDuration": {
"value": 3,
"unit": "months",
"code": "mo",
"system": "http://unitsofmeasure.org"
},
"frequency": 1,
"period": 1,
"periodUnit": "mo"
}
},
"authoredOn": "2019-02-15",
"requester": {
"reference": "http://example.org/fhir/PractitionerRole/987",
"display": "Dr. Jones"
}
}
}
]
}
],
"selectionBehavior": "any"
},
{
"extension": {
"davinci-crd.associated-resource": [
{
"reference": "MedicationRequest/2222"
}
]
},
"uuid": "ba18576a-1905-4e2c-b5fd-cf04171dc291",
"summary": "Complete Opiod Use form",
"detail": "Form ABC is required to attest to appropriate opiod usage",
"indicator": "info",
"source": {
"label": "Centers for Medicare & Medicaid Services",
"url": "https://cms.gov",
"topic": {
"system": "http://example.org/fhir/CodeSystem/SomeCodes",
"code": "123",
"display": "Regulatory Requirement"
}
},
"suggestions": [
{
"label": "Add 'completion of the ABC form' to your task list (possibly for reassignment)",
"actions": [
{
"type": "create",
"description": "Add version 2 of the XYZ form to the clinical system's repository (if it doesn't already exist)",
"resource": {
"resourceType": "Questionnaire",
"id": "1",
"url": "http://example.org/Questionnaire/XYZ",
"version": "2",
"status": "active",
"item": [
{
"linkId": "1",
"text": "Has the patient previously tried non-opioid therapy and been unsuccessful?",
"type": "boolean"
}
]
},
"extension": {
"davinci-crd.if-none-exist": "url=http://example.org/Questionnaire/XYZ&version;=2"
}
},
{
"type": "create",
"description": "Add 'Complete ABC form' to the task list",
"resource": {
"resourceType": "Task",
"id": "1",
"basedOn": [
{
"reference": "http://example.org/fhir/Appointment/27"
}
],
"status": "ready",
"intent": "order",
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/uv/sdc/CodeSystem/temp",
"code": "complete-questionnaire"
}
]
},
"description": "Complete XYZ form for local retention",
"for": {
"reference": "http://example.org/fhir/Patient/123"
},
"authoredOn": "2018-08-09",
"input": [
{
"type": {
"text": "questionnaire"
},
"valueCanonical": "http://example.org/Questionnaire/XYZ|2"
},
{
"type": {
"text": "afterCompletion"
},
"valueCodeableConcept": {
"coding": [
{
"system": "http://example.org/fhir/CodeSystem/SomeCodes",
"code": "987",
"display": "Local Use"
}
]
}
}
]
}
}
]
}
],
"selectionBehavior": "any"
},
{
"uuid": "5561ec1e-78c5-48aa-8fc0-037c476452bf",
"summary": "Patient coverage information is incomplete",
"indicator": "info",
"source": {
"label": "Some Payer",
"url": "https://example.com",
"icon": "https://example.com/img/icon-100px.png",
"topic": {
"system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"code": "insurance",
"display": "Insurance"
}
},
"suggestions": [
{
"label": "Update coverage information to be current",
"uuid": "1207df9d-9ff6-4042-985b-b8dec21038c2",
"actions": [
{
"type": "update",
"description": "Update current coverage record",
"resource": {
"resourceType": "Coverage",
"id": "1234",
"status": "active",
"subscriberId": "192837",
"beneficiary": {
"reference": "http://example.org/fhir/Patient/123"
},
"period": {
"start": "2023-01-01",
"end": "2023-11-30"
},
"payor": [
{
"reference": "http://example.org/fhir/Organization/ABC"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}
]
},
"value": "A1"
}
]
}
}
]
}
],
"selectionBehavior": "any"
},
{
"extension": {
"davinci-crd.associated-resource": [
{
"reference": "MedicationRequest/2222"
}
]
},
"uuid": "353cd963-2ecd-46f9-958b-ed7d2bbf6e01",
"summary": "Launch opioid XYZ-assessment",
"indicator": "info",
"source": {
"label": "Some Payer",
"url": "https://example.com",
"icon": "https://example.com/img/icon-100px.png",
"topic": {
"system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"code": "guideline",
"display": "Guideline"
}
},
"links": [
{
"label": "Opioid XYZ-assessment",
"url": "https://example.org/opioid-assessment",
"type": "smart",
"appContext": "{\"payerXYZQNum\":\"205f471f-f408-45d4-9213-0eedf95f417f\"}"
}
]
}
]
}
Error Responses
Status code 400 Bad Request
The request is incomplete or badly structured.
Status code 401 Unauthorized
The bearer token used for authentication failed validation (if it expired, for example).
Status code 404 Not Found
An error due to missing authorization data or failed authorization.
Status code 412 Precondition Failed
An error when trying to fetch necessary FHIR data.
Status code 500 Internal Server Error
A generic error message, returned when no more specific message is suitable.
An example internal server error message is as follows:
{
"errors": [
{
"code": 5001,
"domain": "%ObjectErrors",
"error": "ERROR #5001: hookInstance value is not unique: HHGFDH10-75GF-13EF-JJR6-0BBNRNP4234",
"id": "GeneralError",
"params": [
"hookInstance value is not unique: HHGFDH10-75GF-13EF-JJR6-0BBNRNP4234"
]
}
],
"summary": "ERROR #5001: hookInstance value is not unique: HHGFDH10-75GF-13EF-JJR6-0BBNRNP4234"
}