Using the DTR (Documentation Templates and Rules) API

 

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:

  • Retrieving the payer’s Questionnaire package using the $questionnaire-package operation.
  • Retrieving the next questions of an adaptive Questionnaire using the $next-question operation.
  • Reporting errors found in the payer’s Questionnaire or CQL using the $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.

Calling the Questionnaire Package

 

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: Required. The 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: Optional. A list of canonical URLs of specific Questionnaire resources to retrieve.
  • order: Optional. One or more order resources, such as ServiceRequest or Encounter, to provide context.
  • referenced: Optional, STU 2.1 only. Resources referenced by the order, such as the Patient, requester, performer, and location, to support stand-alone launch. STU 2.2 removed this parameter.
  • context: Optional. A context ID provided in a previous DTR session.
  • changedsince: Optional. The 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:

  • PackageBundle (STU 2.1) or packagebundle (STU 2.2): A collection of resources representing the retrieved Questionnaire package. This typically includes:
    • Questionnaire: The structured documentation template(s) to be completed.
    • QuestionnaireResponse: The corresponding response(s) to the Questionnaire.
    • Library: Any associated CQL libraries used for evaluation.
    • ValueSet: Any associated ValueSets referenced by the Questionnaire.

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"
            }
          }
        ]
      }
    }
  ]
}

Calling the Next Question Operation

 

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:

  • questionnaire-response: The 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.

Logging Questionnaire Errors

 

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: The canonical URL of the Questionnaire that produced the errors.
  • operationOutcome: An 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]"
      ]
    }
  ]
}