FHIR $questionnaire-package operation for HealthLake

The $questionnaire-package operation retrieves a comprehensive bundle containing a FHIR Questionnaire and all its dependencies needed to render and process the questionnaire. This operation implements the Da Vinci Documentation Templates and Rules (DTR) Implementation Guide, enabling dynamic form rendering for documentation requirements in healthcare workflows.

How it works

Use Cases

API endpoint

POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json

Request parameters

Input parameters

The request body must contain a FHIR Parameters resource with the following parameters:

Parameter validation rules

At least ONE of the following must be provided (in addition to required coverage):

Valid Request Combinations:

Example request

POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": {  
        "resourceType": "Coverage",  
        "id": "example-coverage",  
        "status": "active",  
        "beneficiary": {  
          "reference": "Patient/example-patient"  
        },  
        "payor": [{  
          "reference": "Organization/example-payer"  
        }],  
        "class": [{  
          "type": {  
            "coding": [{  
              "system": "http://terminology.hl7.org/CodeSystem/coverage-class",  
              "code": "group"  
            }]  
          },  
          "value": "12345"  
        }]  
      }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "id": "example-service-request",  
        "status": "active",  
        "intent": "order",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660",  
            "display": "Continuous positive airway pressure ventilation (CPAP)"  
          }]  
        },  
        "subject": {  
          "reference": "Patient/example-patient"  
        }  
      }  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-01-01T00:00:00Z"  
    }  
  ]  
}

Response format

Success response (200 OK)

The operation returns a FHIR Parameters resource containing one or more Package Bundles. Each Package Bundle includes:

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "PackageBundle",  
      "resource": {  
        "resourceType": "Bundle",  
        "id": "questionnaire-package-example",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]  
        },  
        "type": "collection",  
        "timestamp": "2024-03-15T10:30:00Z",  
        "entry": [  
          {  
            "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
            "resource": {  
              "resourceType": "Questionnaire",  
              "id": "home-oxygen-therapy",  
              "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
              "version": "2.0",  
              "status": "active",  
              "title": "Home Oxygen Therapy Documentation",  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "type": "choice",  
                  "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"  
                }  
              ]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",  
            "resource": {  
              "resourceType": "Library",  
              "id": "oxygen-prepopulation",  
              "url": "http://example.org/fhir/Library/oxygen-prepopulation",  
              "version": "1.0",  
              "type": {  
                "coding": [{  
                  "system": "http://terminology.hl7.org/CodeSystem/library-type",  
                  "code": "logic-library"  
                }]  
              },  
              "content": [{  
                "contentType": "text/cql",  
                "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."  
              }]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
            "resource": {  
              "resourceType": "ValueSet",  
              "id": "oxygen-diagnoses",  
              "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
              "status": "active",  
              "expansion": {  
                "timestamp": "2024-03-15T10:30:00Z",  
                "contains": [  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J44.0",  
                    "display": "COPD with acute lower respiratory infection"  
                  },  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J96.01",  
                    "display": "Acute respiratory failure with hypoxia"  
                  }  
                ]  
              }  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",  
            "resource": {  
              "resourceType": "QuestionnaireResponse",  
              "id": "example-prepopulated",  
              "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",  
              "status": "in-progress",  
              "subject": {  
                "reference": "Patient/example-patient"  
              },  
              "basedOn": [{  
                "reference": "ServiceRequest/example-service-request"  
              }],  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "answer": [{  
                    "valueCoding": {  
                      "system": "http://hl7.org/fhir/sid/icd-10",  
                      "code": "J44.0",  
                      "display": "COPD with acute lower respiratory infection"  
                    }  
                  }]  
                }  
              ]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "name": "Outcome",  
      "resource": {  
        "resourceType": "OperationOutcome",  
        "issue": [{  
          "severity": "information",  
          "code": "informational",  
          "details": {  
            "text": "Successfully retrieved questionnaire package"  
          }  
        }]  
      }  
    }  
  ]  
}

Operation workflow

How HealthLake Processes Your Request

When you call $questionnaire-package, HealthLake performs the following steps:

Result: A complete, self-contained package ready for rendering.

Error responses

400 Bad Request

Returned when request validation fails.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}

424 Failed Dependency

Returned when a dependent resource cannot be retrieved.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}

401 Unauthorized

Returned when authentication credentials are missing or invalid.

403 Forbidden

Returned when the authenticated user lacks permission to access the requested resources.

406 Not Acceptable

Returned when the requested content type cannot be provided.

409 Conflict

Returned when there's a version or concurrency conflict.

410 Gone

Returned when the requested resource has been permanently deleted.

429 Too Many Requests

Returned when rate limits are exceeded.

500 Internal Server Error

Returned when an unexpected server error occurs.

501 Not Implemented

Returned when the requested operation is not yet implemented.

Validation rules

Input validation

QuestionnaireResponse validation

Resource deduplication

Performance specifications

Required permissions

To use the $questionnaire-package operation, ensure your IAM role has:

SMART on FHIR Scopes

Minimum required scopes:

Important implementation notes

Resource retrieval strategy

Questionnaire Identification Priority:

Dependency resolution

CQL Libraries:

ValueSets:

QuestionnaireResponse pre-population

The operation may return a QuestionnaireResponse with pre-populated data when:

Search Criteria for QuestionnaireResponse:

Changed resources filtering

When the changedSince parameter is provided:

Multiple package bundles

The operation may return multiple Package Bundles when:

Each Package Bundle is self-contained with all necessary dependencies.

Common use cases

Use Case 1: Prior Authorization Documentation

Scenario: A provider needs to collect documentation for a home oxygen therapy prior authorization.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Patient's insurance coverage */ }  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660"  
          }]  
        }  
      }  
    }  
  ]  
}

Result: Returns a package with the oxygen therapy questionnaire, pre-populated with patient vitals and diagnosis codes from the EHR.

Use Case 2: Retrieve Specific Questionnaire Version

Scenario: A provider needs a specific version of a questionnaire for compliance.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}

Result: Returns exactly version 3.1.0 of the DME request questionnaire with all dependencies.

Use Case 3: Check for Updates

Scenario: A provider wants to check if any questionnaire resources have been updated since last retrieval.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-03-01T00:00:00Z"  
    }  
  ]  
}

Result: Returns only resources that have been modified after March 1, 2024, or an empty package if nothing changed.

Use Case 4: Multiple Orders

Scenario: A provider submits multiple service requests that may require different questionnaires.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}

Result: Returns multiple Package Bundles, one for each applicable questionnaire.

Integration with Other Da Vinci IGs

Coverage Requirements Discovery (CRD)

Workflow Integration:

Prior Authorization Support (PAS)

Workflow Integration:

Clinical Data Exchange (CDex)

Workflow Integration:

Troubleshooting guide

Issue: No Questionnaire Returned

Possible Causes:

Solutions:

Issue: Missing Dependencies in Package

Possible Causes:

Solutions:

Issue: Empty Package with changedSince

Possible Causes:

Solutions:

Issue: QuestionnaireResponse Not Pre-populated

Possible Causes:

Solutions:

Best practices

1. Use Canonical URLs with Versions

Always specify version numbers when requesting specific questionnaires:

{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}

Why: Ensures consistency and prevents unexpected changes when questionnaires are updated.

2. Leverage changedSince for Performance

For frequently accessed questionnaires, use changedSince to minimize data transfer:

{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}

Why: Reduces latency and bandwidth usage by retrieving only updated resources.

3. Include Complete Coverage Information

Provide comprehensive coverage details to ensure correct questionnaire selection:

{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}

Why: Helps HealthLake identify payer-specific questionnaires and requirements.

Related operations