This tutorial demonstrates how an in-network provider can retrieve structured documentation templates (Questionnaire packages) from a payer to support prior authorization requests. It covers:
$questionnaire-package operation.$next-question operation.$log-questionnaire-errors operation.Where a parameter differs between DTR STU 2.1 and STU 2.2, the difference is noted. See Supported Implementation Guide Versions.
Providers call the $questionnaire-package FHIR operation to retrieve the payer’s structured documentation templates.
HTTP Request:
POST [PAYER_BASE_URL]/Questionnaire/$questionnaire-package
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json
Request Body:
The body of the POST request must contain the Parameters resource with the following input parameters:
Coverage resource identifying the member and the type of coverage for which additional information is needed. STU 2.2 constrains it to exactly one; STU 2.1 allowed zero or more. A request without it returns 422 Unprocessable Entity.Questionnaire resources to retrieve.ServiceRequest or Encounter, to provide context.Patient, requester, performer, and location, to support stand-alone launch. STU 2.2 removed this parameter.meta.lastUpdated timestamp to retrieve updated QuestionnaireResponse resources. STU 2.2 changed its type from dateTime to instant.For detailed definitions and constraints, refer to the DTR Questionnaire Package Input Parameters.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"id": "example-coverage-1",
"status": "active",
"beneficiary": {
"reference": "Patient/example-patient-1"
},
"payor": [
{
"reference": "Organization/example-payer"
}
]
}
},
{
"name": "order",
"resource": {
"resourceType": "ServiceRequest",
"id": "example-order-1",
"status": "draft",
"intent": "order",
"subject": {
"reference": "Patient/example-patient-1"
}
}
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/example-questionnaire-1"
},
{
"name": "context",
"valueString": "example-context-id"
},
{
"name": "changedsince",
"valueInstant": "2025-10-01T00:00:00Z"
}
]
}
Response Body:
The response to a successful $questionnaire-package operation is a Parameters resource with the following output parameters:
For detailed definitions and constraints, refer to the DTR Questionnaire Package Output Parameters.
STU 2.2 also renamed the operationOutcome output parameter to outcome, and requires each package Bundle to contain exactly one QuestionnaireResponse.
Sample Response:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "PackageBundle",
"resource": {
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "Questionnaire",
"id": "aslp-sleep-study",
"url": "http://example.org/fhir/Questionnaire/aslp-sleep-study",
"status": "active",
"title": "Home Sleep Study Questionnaire",
"item": [
{
"linkId": "1",
"text": "Patient Name",
"type": "string"
},
{
"linkId": "2",
"text": "Date of Sleep Study",
"type": "date"
}
]
}
},
{
"resource": {
"resourceType": "Library",
"id": "sleep-study-cql",
"url": "http://example.org/fhir/Library/sleep-study-cql",
"status": "active"
}
},
{
"resource": {
"resourceType": "ValueSet",
"id": "sleep-study-values",
"url": "http://example.org/fhir/ValueSet/sleep-study-values",
"status": "active"
}
}
]
}
}
]
}
Adaptive Questionnaires do not list all of their questions up front. The provider calls the Questionnaire/$next-question operation to retrieve the next question (or set of questions), based on the answers given so far.
HTTP Request:
POST [PAYER_BASE_URL]/Questionnaire/$next-question
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json
Request Body:
The body of the POST request must contain a Parameters resource with the following input parameter:
QuestionnaireResponse being completed. It must contain the adaptive Questionnaire as a contained resource, and its questionnaire element must reference that contained resource. On the first call, neither resource has any items. On later calls, the QuestionnaireResponse includes the answers to the questions asked so far, and the contained Questionnaire is unchanged from the previous response.The payer uses the contained Questionnaire's url to decide how to process the request. The payer must have an active Questionnaire with the same url.
For detailed definitions and constraints, refer to the SDC Next Question Operation.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "questionnaire-response",
"resource": {
"resourceType": "QuestionnaireResponse",
"contained": [
{
"resourceType": "Questionnaire",
"id": "home-o2-adaptive-questionnaire",
"url": "http://example.com/fhir/Questionnaire/home-o2-adaptive",
"status": "active",
"extension": [
{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-questionnaireAdaptive",
"valueUrl": "http://example.com/fhir/R4"
}
]
}
],
"questionnaire": "#home-o2-adaptive-questionnaire",
"status": "in-progress",
"subject": {
"reference": "Patient/example-patient-1"
}
}
}
]
}
Response Body:
A successful response is the QuestionnaireResponse. Its contained Questionnaire includes the next question(s), and its item elements include the answers given so far. Send the response back, with the new questions answered, to retrieve the following question(s).
The adaptive Questionnaire is complete when the payer returns the QuestionnaireResponse with a status of completed.
If the contained Questionnaire has no url, or the payer has no matching Questionnaire, the operation returns 422 Unprocessable Entity with an OperationOutcome describing the problem.
When the provider’s DTR application finds a problem in a payer’s Questionnaire or its CQL, for example a CQL expression that fails to run, it reports the problem to the payer with the Questionnaire/$log-questionnaire-errors operation.
HTTP Request:
POST [PAYER_BASE_URL]/Questionnaire/$log-questionnaire-errors
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/fhir+json
Accept: application/fhir+json
Request Body:
The body of the POST request must contain a Parameters resource with the following input parameters. Both are required:
Questionnaire that produced the errors.OperationOutcome describing each error and where it occurred.These are the STU 2.2 parameter names. STU 2.1 named them Questionnaire and OperationOutcome, and STU 2.2's input Parameters profile names the second parameter outcome. Parameter names are case-sensitive, so only the names above are accepted.
For detailed definitions and constraints, refer to the DTR Log Questionnaire Errors Operation.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/aslp-sleep-study"
},
{
"name": "operationOutcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "CQL expression 'SleepStudyDate' failed: Could not resolve identifier 'ServiceRequest'",
"expression": [
"Questionnaire.item[1]"
]
}
]
}
}
]
}
Response Body:
The payer stores the OperationOutcome and returns it with its new resource ID. The stored resource has two extensions added: the Questionnaire URL that produced the errors, and a note that it was generated by the $log-questionnaire-errors operation.
If either parameter is missing, the operation returns 400 Bad Request.
{
"resourceType": "OperationOutcome",
"id": "1052",
"extension": [
{
"url": "https://smiledigitalhealth.com/priorauth/populate-operation-outcome",
"valueString": "http://example.org/fhir/Questionnaire/aslp-sleep-study"
},
{
"url": "https://smiledigitalhealth.com/priorauth/log-questionnaire-error",
"valueString": "This resource was generated by the $log-questionnaire-errors endpoint"
}
],
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "CQL expression 'SleepStudyDate' failed: Could not resolve identifier 'ServiceRequest'",
"expression": [
"Questionnaire.item[1]"
]
}
]
}
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.