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 using the DTR $expand API.
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:
{
"resourceType": "Parameters",
"id": "QuestionnairePackageInputParamsExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-qpackage-input-parameters"
]
},
"parameter": [
{
"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. One bundle of one or more questionnaires is returned. Example body content:
{
"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
},
{
"linkId": "T-5_Q-18",
"text": "Are you worried that in the next month, you may not have stable housing?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-19",
"text": "Do problems with child care make it difficult for you to work or study?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-20",
"text": "In the last month, have you ever had to go without healthcare because you didn't have a way to get there?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-21",
"text": "Do you ever need help reading hospital materials?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-22",
"text": "Are you afraid you might be hurt in your apartment building or house?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-23",
"text": "Would you have someone to help out if you were sick and needed to be in bed?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-24",
"text": "Do you have someone to take you to a clinic or doctor's office if you needed a ride?",
"type": "text",
"required": false,
"repeats": false
},
{
"linkId": "T-5_Q-25",
"text": "Do you (CHW) see a need for referral to a Care Manager?",
"type": "text",
"required": false,
"repeats": false
},
{
"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"
}
}
]
}
},
{
"name": "operationOutcome"
}
]
}
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:
-
Multiple questionnaires were found for the given canonical URL.
-
The pattern value of the name parameter in the input parameters profile is not questionnaire.
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" }
}
]
}
}
]
}
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.