DTR $questionnaire-package FHIR API Specification
Service Overview
InterSystems DTR (Documentation Template and Rules) FHIR APIs are designed in compliance with the CMS-0057-F regulationsOpens in a new tab.
Refer to the Getting Started section for information on connectivity, authentication and how to get help. To use the FHIR APIs, you will need to know the base URL of the FHIR server you will be connecting to. You can also retrieve the capability statement for the service.
As part of the DTR APIs, a provider can use the $questionnaire-package API to obtain one or more questionnaires based on pre-defined payer requirements. Any value sets that are referenced by the questionnaires returned from the $questionnaire-package API will automatically be expanded when possible.
Workflow
A typical workflow involving the questionnaire package operation might be:
-
A provider’s electronic health record (EHR) system is configured for DTR application connectivity.
-
The EHR and DTR app are configured for payer connectivity.
-
The EHR, via the DTR app, uses pre-defined payer information to send a documentation request to the payer.
-
The payer organization returns a bundle of one or more questionnaires.
-
The DTR app pre-fills the questionnaire(s) as much as possible, retrieving data, requesting data from the EHR as needed.
-
A user verifies the questionnaire data.
-
The completed questionnaire is stored in the EHR and can be used in downstream processes.
Prerequisites
None.
Endpoint: $questionnaire-package
URL
The questionnaire package URL is:
<BaseURL>/Questionnaire/$questionnaire-package
Optional Capabilities
None.
Endpoint Prerequisites
None.
Required Header Settings
-
Content-Type: application/json+fhir
-
Accept: application/json+fhir
Request Methods
Invokes the questionnaire package operation.
This method should be called asynchronously as locating a questionnaire from a FHIR repository may take an indeterminate amount of time to return a response.
Query Parameters
None.
Request Body
The questionnaire package operation requires the pattern value of the questionnaire name parameter in the input parameters profile to be questionnaire.
Sample Request
The following shows sample request body content including the questionnaire input parameter with a Coverage resource:
{
"resourceType": "Parameters",
"id": "QuestionnairePackageInputParamsExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-qpackage-input-parameters"
]
},
"parameter": [
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"id": "example",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Coverage example</b></p></div>"
},
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB"
}
]
},
"system": "http://example.com/fhir/NamingSystem/certificate",
"value": "12345"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "EHCPOL",
"display": "extended healthcare"
}
]
},
"beneficiary": {
"reference": "Patient/example"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
]
},
"payor": [
{
"reference": "http://example.org/fhir/Organization/example-payer",
"display": "Payer XYZ"
}
]
}
},
{
"name": "questionnaire",
"valueCanonical": "fhir://a_server:Questionnaire/5"
}
]
}
Note that the parameter object could contain multiple questionnaire name-value pairs.
A request can generally be expected to return one bundle of one or more questionnaires that match the given input questionnaire URL.
Success Responses
The request succeeded. Zero questionnaires were found, or one bundle of one or more questionnaires is returned.
Example body content when a questionnaire has been found (some items from the item array have been snipped for brevity):
{
"resourceType": "Parameters",
"id": "60531e18-fc87-46f2-8231-54a15d112036",
"parameter": [
{
"name": "PackageBundle",
"resource": {
"resourceType": "Bundle",
"id": "1edb289e-df9b-43a6-afb9-af651fa3bab9",
"type": "collection",
"timestamp": "2024-03-20T19:06:37Z",
"total": 1,
"entry": [
{
"fullUrl": "https://a_server/Questionnaire/5",
"resource": {
"id": "5",
"resourceType": "Questionnaire",
"identifier": [
{
"use": "official",
"system": "CareCommunity",
"value": "T-5"
}
],
"url": "fhir://a_server:Questionnaire/5",
"version": "1",
"name": "Social Needs",
"title": "Social Needs",
"status": "active",
"subjectType": [
"Patient"
],
"date": "2024-03-08T18:34:54.906Z",
"publisher": "CareCommunity",
"approvalDate": "2024-03-08",
"item": [
{
"linkId": "T-5_Summary",
"text": "Your Community Health Worker will help you identify social needs and develop a care plan to address them using this tool.",
"type": "display"
},
{
"linkId": "T-5_Q-16",
"text": "In the last month did you eat less than you felt you should because there wasn't enough money for food?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-17",
"text": "In the last month has any utility company shut off your service for not paying bills?",
"type": "text",
"required": false,
"repeats": false
},
<--snipped-->
{
"linkId": "T-5_Q-26",
"text": "Do you (CHW) see a need for referral to Financial Assistance?",
"type": "text",
"required": false,
"repeats": false
}
],
"meta": {
"lastUpdated": "2024-03-19T20:30:42Z",
"versionId": "2"
}
},
"search": {
"mode": "match"
}
},
{
"resourceType": "QuestionnaireResponse",
"id": "cab4c0bb-7118-4b24-b8d7-930261981cc7",
"extension" : [
{
"url" : "http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/qr-context",
"valueReference" : {
"reference" : "Coverage/CoverageExample"
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/intendedUse",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "http://hl7.org/fhir/us/davinci-crd/CodeSystem/temp",
"code" : "withorder",
"display" : "Include with order"
}
]
}
}
],
"status": "in-progress",
"questionnaire": "fhir://a_server:Questionnaire/5"
}
]
}
}
]
}
Example body content when no matching questionnaires were found:
{
"resourceType": "Parameters",
"id": "c35d00e8-5c91-4a2b-aeb7-f4883352a367",
"parameter": [
{
"name": "operationOutcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "warning",
"code": "not-found",
"diagnostics": "<HSFHIRErr>ResourceNotFound",
"details": {
"text": "No matching questionnaires were found"
}
}
]
}
}
]
}
Partial Content. The request succeeded but with only partial content. One bundle of one or more questionnaires is returned, but did not include all the requested questionnaires.
Example response body content following a request with two questionnaire URLs, but only one questionnaire was found:
{
"resourceType": "Parameters",
"id": "bfff2efe-b183-43c6-9bea-9cf4d14f2952",
"parameter": [
{
"name": "PackageBundle",
"resource": {
"resourceType": "Bundle",
"id": "4b96b915-5b1f-40d9-a8ec-f9ee99914b29",
"type": "collection",
"timestamp": "2024-03-26T16:35:26Z",
"total": 1,
"entry": [
{...
}
]
}
},
{
"name": "operationOutcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "warning",
"code": "not-found",
"diagnostics": "
"text": "There is no matching questionnaire with the canonical url: fhir://a_server:Questionnaire/5"
}
}
]
}
}
]
}
Error Responses
The following response error codes are possible when using the questionnaire package operation:
Bad Request. Possible causes include:
-
Incorrect payload structure.
-
The pattern value of the name parameter in the input parameters profile is not questionnaire.
-
The included Coverage resource is missing required fields or contains invalid or missing values, or contains nested resources.
Example response body content when the pattern value of the questionnaire name parameter in the input parameters profile of the request is not questionnaire:
{
"resourceType": "Parameters",
"id": "e387c574-0e64-4ca0-8b02-8c2576f5fc04",
"parameter": [
{
"name": "operationOutcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "warning",
"code": "exception",
"diagnostics": "<HSFHIRErr>OperationPayloadMissing",
"details": {
"text": "Pattern value for questionnaire name parameter is not 'questionnaire'"
}
}
]
}
}
]
}
Not Found. Possible causes include:
-
A questionnaire with the given canonical URL was not found.
Example response body content:
{
"resourceType": "Parameters",
"id": "eca07414-810b-4b22-8574-d0fcb8611406",
"parameter": [
{
"name": "operationOutcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "warning",
"code": "not-found",
"diagnostics": "<HSFHIRErr>ResourceNotFound",
"details": {
"text": "There is no matching questionnaire with the canonical url: fhir://a_server:Questionnaire/45" }
}
]
}
}
]
}
Resource Not Found. Possible causes include:
-
A Utilization Management system retrieval error.
Service Unavailable. Possible causes and return messages include:
-
The $questionnaire-package endpoint is not properly set, or does not return a response, the error includes a no-store message.
-
An unregistered operation or resource is requested, the error message includes The handler for operation '[operation]' for resource type '[resource type]/[resource id]' is not registered.