CRD Discovery REST API Specification
Overview
As part of the InterSystems® Payer Services CRD (Coverage Requirements Discovery) REST APIs, a provider can use the discovery endpoint to determine information about the CDS Hooks services available from their patient’s payer. The returned information includes a description of the services, the HL7® FHIR® resources required by each, and any data that is requested to be prefetched. If you support prefetch, you can use this endpoint to determine the prefetch key names and queries of the payer’s service.
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.
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 discovery API is as follows:
-
A provider’s client application sends a request to the CDS Hooks server’s discovery endpoint (this API) to receive information about the services that are available at that server, including the HL7® FHIR® resources required by each service.
-
The client invokes one of the available services by sending a request to the relevant service endpoint. 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
URL
The URL for this REST API is:
<BaseURL>/csp/healthshare/<namespace_identifier>/cds-hooks/r4/cds-services
where <BaseURL> and <namespace_identifier> have been provided to you by the payer organization you are connecting with.
Optional Capabilities
None.
Endpoint Prerequisites
-
You know the base URL for your payer’s CRD server
-
You have requested authorization tokens from your payer's authorization server to call their endpoints
-
You have established access control policies such that your payer (after receiving the FHIR authorization token from your CRD service request) can access relevant data from your FHIR server as required by their adjudication process
Required Header Settings
-
Accept: application/json
Request Methods
GET <BaseURL>/csp/healthshare/<namespace_identifier>/cds-hooks/r4/cds-services
Invokes the request to obtain a service description for each of the CDS Hooks supported by the patient’s payer system.
Query Parameters
None.
Request Body
None.
Success Response
Status code 200
The request was invoked successfully.
The body of the response is a CDS Hooks discovery responseOpens in a new tab. This response includes an array of JSON objects which describe each service that is currently available on the payer system. The information can then be used to construct a CRD service API request to a particular service. If the request succeeded but no services are available, the response body contains an empty services array.
An example of a returned response body is shown below:
{
"services": [
{
"id": "order-sign-crd",
"hook": "order-sign",
"title": "order-sign Coverage Requirements Discovery",
"description": "Get information regarding the coverage requirements for durable medical equipment",
"prefetch": {
"serviceRequestBundle": "ServiceRequest?_id={{context.draftOrders.ServiceRequest.id}}&_include;=ServiceRequest:patient&_include;=ServiceRequest:performer&_include;=ServiceRequest:requester&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"medicationRequestBundle": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"coverageBundle": "Coverage?patient={{context.patientId}}",
"deviceRequestBundle": "DeviceRequest?_id={{context.draftOrders.DeviceRequest.id}}&_include;=DeviceRequest:patient&_include;=DeviceRequest:performer&_include;=DeviceRequest:requester&_include;=DeviceRequest:device&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner"
},
"usageRequirements": "String userId, String patientId, object draftOrders",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "deviceRequestBundle",
"query": "DeviceRequest?_id={{context.draftOrders.DeviceRequest.id}}&_include;=DeviceRequest:patient&_include;=DeviceRequest:performer&_include;=DeviceRequest:requester&_include;=DeviceRequest:device&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "medicationRequestBundle",
"query": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "serviceRequestBundle",
"query": "ServiceRequest?_id={{context.draftOrders.ServiceRequest.id}}&_include;=ServiceRequest:patient&_include;=ServiceRequest:performer&_include;=ServiceRequest:requester&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "alt-drug",
"type": "boolean",
"name": "Alternative therapy",
"description": "Provides recommendations for alternative therapy with equivalent/similar clinical effect for which the patient has better coverage, that will incur lesser code",
"value": "true"
},
{
"code": "dtr-clin",
"type": "boolean",
"name": "DTR Clin",
"description": "Indication that DTR is relevant for prior authorization, claim or other documentation requirements and that at least some clinical information needs to be captured",
"value": "true"
},
{
"code": "prior-auth",
"type": "boolean",
"name": "Prior Auth",
"description": "Provides indications of whether prior authorization is required for the proposed order",
"value": "true"
},
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed order",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
},
{
"id": "order-select-crd",
"hook": "order-select",
"title": "order-select Coverage Requirements Discovery",
"description": "Get information regarding the coverage requirements for durable medical equipment",
"prefetch": {
"medicationRequestBundle": "MedicationRequest?_id={{context.draftOrders.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"coverageBundle": "Coverage?patient={{context.patient}}",
"medicationStatementBundle": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner"
},
"usageRequirements": "String userId, String patientid, array selections, object draftODers",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patient}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "medicationStatementBundle",
"query": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "medicationRequestBundle",
"query": "MedicationRequest?_id={{context.draftOrders.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed order",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
},
{
"id": "appointment-book-crd",
"hook": "appointment-book",
"title": "appointment-book Coverage Requirements Discovery",
"description": "Get information regarding the coverage requirements for appointments",
"prefetch": {
"encounterBundle": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"patient": "Patient/{{context.patientId}}",
"coverageBundle": "Coverage?patient={{context.patientId}}"
},
"usageRequirements": "String, userID, String patientid, object appointments",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "patient",
"query": "Patient/{{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Patient"
},
{
"key": "encounterBundle",
"query": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed appointment(s)",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
},
{
"id": "order-dispatch-crd",
"hook": "order-dispatch",
"title": "order-dispatch Coverage Requirements Discovery",
"description": "test",
"prefetch": {
"serviceRequestBundle": "ServiceRequest?_id={{context.draftOrders.ServiceRequest.id}}&_include;=ServiceRequest:patient&_include;=ServiceRequest:performer&_include;=ServiceRequest:requester&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"medicationRequestBundle": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"coverageBundle": "Coverage?patient={{context.patientId}}",
"deviceRequestBundle": "DeviceRequest?_id={{context.draftOrders.DeviceRequest.id}}&_include;=DeviceRequest:patient&_include;=DeviceRequest:performer&_include;=DeviceRequest:requester&_include;=DeviceRequest:device&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner"
},
"usageRequirements": "String patientid, array dispatchedOrders, String performer",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "deviceRequestBundle",
"query": "DeviceRequest?_id={{context.draftOrders.DeviceRequest.id}}&_include;=DeviceRequest:patient&_include;=DeviceRequest:performer&_include;=DeviceRequest:requester&_include;=DeviceRequest:device&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "medicationRequestBundle",
"query": "MedicationRequest?_id={{context.medications.MedicationRequest.id}}&_include;=MedicationRequest:patient&_include;=MedicationRequest:intended-dispenser&_include;=MedicationRequest:requester:PractitionerRole&_include;=MedicationRequest:medication&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "serviceRequestBundle",
"query": "ServiceRequest?_id={{context.draftOrders.ServiceRequest.id}}&_include;=ServiceRequest:patient&_include;=ServiceRequest:performer&_include;=ServiceRequest:requester&_include;:iterate=PractitionerRole:organization&_include;:iterate=PractitionerRole:practitioner",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "alt-drug",
"type": "boolean",
"name": "Alternative therapy",
"description": "Provides recommendations for alternative therapy with equivalent/similar clinical effect for which the patient has better coverage, that will incur lesser code",
"value": "true"
},
{
"code": "dtr-clin",
"type": "boolean",
"name": "DTR Clin",
"description": "Indication that DTR is relevant for prior authorization, claim or other documentation requirements and that at least some clinical information needs to be captured",
"value": "true"
},
{
"code": "prior-auth",
"type": "boolean",
"name": "Prior Auth",
"description": "Provides indications of whether prior authorization is required for the proposed order",
"value": "true"
},
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed order",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
},
{
"id": "encounter-start-crd",
"hook": "encounter-start",
"title": "encounter-start Coverage Requirements Discovery",
"description": "Get information regarding the coverage requirements for encounters",
"prefetch": {
"encounterBundle": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"patient": "Patient/{{context.patientId}}",
"coverageBundle": "Coverage?patient={{context.patientId}}"
},
"usageRequirements": "String userId, String patientid, String encounterID",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "patient",
"query": "Patient/{{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Patient"
},
{
"key": "encounterBundle",
"query": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed appointment(s)",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
},
{
"id": "encounter-discharge-crd",
"hook": "encounter-discharge",
"title": "encounter-discharge Coverage Requirements Discovery",
"description": "Get information regarding the coverage requirements for encounters",
"prefetch": {
"encounterBundle": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"patient": "Patient/{{context.patientId}}",
"coverageBundle": "Coverage?patient={{context.patientId}}"
},
"usageRequirements": "String userId, String patientid, String encounterID",
"prefetchElements": [
{
"key": "coverageBundle",
"query": "Coverage?patient={{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Bundle"
},
{
"key": "patient",
"query": "Patient/{{context.patientId}}",
"returnType": "org.hl7.fhir.r4.model.Patient"
},
{
"key": "encounterBundle",
"query": "Encounter?_id={{context.encounterId}}&_include;=Encounter:patient&_include;=Encounter:service-provider&_include;=Encounter:practitioner&_include;=Encounter:location",
"returnType": "org.hl7.fhir.r4.model.Bundle"
}
],
"extension": {
"davinci-crd.configuration-options": [
{
"code": "coverage",
"type": "boolean",
"name": "Coverage",
"description": "Provides indications of whether coverage is required for the proposed appointment(s)",
"value": "true"
},
{
"code": "max-cards",
"type": "integer",
"name": "Maximum cards",
"description": "Indicates the maximum number of cards to be returned from the service. The services will prioritize cards such as highest priority ones are delivered",
"value": "10"
}
]
}
}
]
}
Error Responses
Status code 401 Unauthorized
The bearer token used for authentication failed validation (if it expired, for example).
Status code 500 Internal Server Error
A generic error message, returned when no more specific message is suitable.