Skip to main content

QuestionnaireResponse

Overview​

The QuestionnaireResponse resource represents completed questionnaires within the Provider Patient Access API. It captures structured responses to questionnaires used for patient assessments, surveys, intake forms, and clinical evaluations in provider-focused healthcare settings.

Key Use Cases:

  • Retrieve completed patient questionnaires and clinical assessments
  • Access structured survey responses and evaluation forms
  • Query questionnaire responses by patient or assessment type
  • Support clinical decision-making through standardized assessments

Relationships to Other Resources:

  • Patient - The patient who completed the questionnaire
  • Practitioner - Healthcare provider who administered or reviewed the questionnaire
  • Encounter - Healthcare encounter during which the questionnaire was completed
  • Questionnaire - The original questionnaire template that was completed

Resource Schema​

Key fields in the QuestionnaireResponse resource:

{
  "resourceType": "QuestionnaireResponse",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/questionnaire-response-id",
      "value": "qr-123"
    }
  ],
  "basedOn": [
    {
      "reference": "ServiceRequest/service-123"
    }
  ],
  "partOf": [
    {
      "reference": "Encounter/encounter-456"
    }
  ],
  "questionnaire": "http://example.org/Questionnaire/phq9",
  "status": "completed",
  "subject": {
    "reference": "Patient/patient-123"
  },
  "encounter": {
    "reference": "Encounter/encounter-456"
  },
  "authored": "2024-01-15T10:30:00Z",
  "author": {
    "reference": "Patient/patient-123"
  },
  "source": {
    "reference": "Patient/patient-123"
  },
  "item": [
    {
      "linkId": "1",
      "text": "Over the last 2 weeks, how often have you been bothered by little interest or pleasure in doing things?",
      "answer": [
        {
          "valueCoding": {
            "system": "http://loinc.org",
            "code": "LA6568-5",
            "display": "Not at all"
          }
        }
      ]
    }
  ]
}

Key Fields:

  • id - Unique identifier for the questionnaire response
  • questionnaire - Reference to the questionnaire that was completed
  • status - Current status of the response (in-progress, completed, amended, etc.)
  • subject - Patient who is the subject of the questionnaire
  • authored - Date and time when the questionnaire was completed
  • author - Person who completed the questionnaire
  • item - Individual question responses with answers

Operations​

Read​

Retrieve a specific questionnaire response by ID.

GET /QuestionnaireResponse/{id}
Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/QuestionnaireResponse/qr-123 \
    -H "Accept: application/fhir+json"

Search for questionnaire responses using various criteria.

GET Method​

Use GET for simple searches with parameters in the query string.

GET /QuestionnaireResponse?parameter=value

POST Method​

Use POST for complex searches with form-encoded parameters.

POST /QuestionnaireResponse/_search

Search Parameters​

Patient-based Search:

ParameterTypeRequiredDescriptionExample
patientreferenceYesPatient who is the subject of the questionnairepatient=Patient/patient-123
authorreferenceNoPerson who completed the questionnaire (Practitioner references supported)author=Practitioner/practitioner-123
authoreddateNoDate when questionnaire was completedauthored=2024-01-15
based-onreferenceNoPlan/proposal/order fulfilled by this questionnaire (CarePlan or ServiceRequest)based-on=ServiceRequest/service-123
part-ofreferenceNoProcedure or encounter this questionnaire is part of (Observation or Procedure)part-of=Encounter/encounter-456
questionnairereferenceNoThe questionnaire the answers are provided forquestionnaire=Questionnaire/phq9
statustokenNoCurrent status of the questionnaire responsestatus=completed
_lastUpdateddateNoLast modification date_lastUpdated=ge2024-01-01

ID-based Search:

ParameterTypeRequiredDescriptionExample
_idtokenYesLogical resource identifier_id=qr-123
authorreferenceNoPerson who completed the questionnaire (Practitioner references supported)author=Practitioner/practitioner-123
authoreddateNoDate when questionnaire was completedauthored=2024-01-15
based-onreferenceNoPlan/proposal/order fulfilled by this questionnaire (CarePlan or ServiceRequest)based-on=ServiceRequest/service-123
part-ofreferenceNoProcedure or encounter this questionnaire is part of (Observation or Procedure)part-of=Encounter/encounter-456
questionnairereferenceNoThe questionnaire the answers are provided forquestionnaire=Questionnaire/phq9
statustokenNoCurrent status of the questionnaire responsestatus=completed
_lastUpdateddateNoLast modification date_lastUpdated=ge2024-01-01

Common Search Patterns​

Find questionnaire responses for a patient:

GET /QuestionnaireResponse?patient=Patient/patient-123&_count=10

Search by questionnaire type:

GET /QuestionnaireResponse?questionnaire=Questionnaire/phq9&patient=Patient/patient-123

Find responses by status:

GET /QuestionnaireResponse?patient=Patient/patient-123&status=completed

Search by date range:

GET /QuestionnaireResponse?patient=Patient/patient-123&authored=ge2024-01-01&authored=le2024-12-31

Find responses based on service request:

GET /QuestionnaireResponse?based-on=ServiceRequest/service-123

Examples​

Request Examples​

Search by patient
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/QuestionnaireResponse/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&_count=10"
Search by questionnaire type
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/QuestionnaireResponse/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "questionnaire=Questionnaire/phq9&patient=Patient/patient-123"
Search by date range
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/QuestionnaireResponse/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&authored=ge2024-01-01&authored=le2024-12-31"

Response Examples​

Successful Search Response​

QuestionnaireResponse Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "id": "qr-123",
        "identifier": [
          {
            "system": "http://example.org/questionnaire-response-id",
            "value": "qr-123"
          }
        ],
        "questionnaire": "http://example.org/Questionnaire/phq9",
        "status": "completed",
        "subject": {
          "reference": "Patient/patient-123"
        },
        "authored": "2024-01-15T10:30:00Z",
        "author": {
          "reference": "Patient/patient-123"
        },
        "item": [
          {
            "linkId": "1",
            "text": "Over the last 2 weeks, how often have you been bothered by little interest or pleasure in doing things?",
            "answer": [
              {
                "valueCoding": {
                  "system": "http://loinc.org",
                  "code": "LA6568-5",
                  "display": "Not at all"
                }
              }
            ]
          },
          {
            "linkId": "2",
            "text": "Over the last 2 weeks, how often have you been bothered by feeling down, depressed, or hopeless?",
            "answer": [
              {
                "valueCoding": {
                  "system": "http://loinc.org",
                  "code": "LA6569-3",
                  "display": "Several days"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Individual QuestionnaireResponse​

Single QuestionnaireResponse Resource
{
  "resourceType": "QuestionnaireResponse",
  "id": "qr-456",
  "identifier": [
    {
      "system": "http://example.org/questionnaire-response-id",
      "value": "qr-456"
    }
  ],
  "basedOn": [
    {
      "reference": "ServiceRequest/service-789"
    }
  ],
  "partOf": [
    {
      "reference": "Encounter/encounter-101"
    }
  ],
  "questionnaire": "http://example.org/Questionnaire/gad7",
  "status": "completed",
  "subject": {
    "reference": "Patient/patient-456"
  },
  "encounter": {
    "reference": "Encounter/encounter-101"
  },
  "authored": "2024-01-20T14:15:00Z",
  "author": {
    "reference": "Practitioner/practitioner-789"
  },
  "source": {
    "reference": "Patient/patient-456"
  },
  "item": [
    {
      "linkId": "1",
      "text": "Feeling nervous, anxious, or on edge",
      "answer": [
        {
          "valueCoding": {
            "system": "http://loinc.org",
            "code": "LA6568-5",
            "display": "Not at all"
          }
        }
      ]
    },
    {
      "linkId": "2",
      "text": "Not being able to stop or control worrying",
      "answer": [
        {
          "valueCoding": {
            "system": "http://loinc.org",
            "code": "LA6570-1",
            "display": "More than half the days"
          }
        }
      ]
    }
  ]
}

Integration Patterns​

Common Workflows​

1. Clinical Assessment Review

# Step 1: Find all questionnaire responses for a patient
GET /QuestionnaireResponse?patient=Patient/patient-123

# Step 2: Get specific questionnaire response details
GET /QuestionnaireResponse/qr-123

# Step 3: Get the original questionnaire for context
GET /Questionnaire/phq9

2. Provider Assessment Tracking

# Step 1: Search for specific assessment type
GET /QuestionnaireResponse?patient=Patient/patient-123&questionnaire=Questionnaire/phq9

# Step 2: Get patient's recent assessments
GET /QuestionnaireResponse?patient=Patient/patient-123&authored=ge2024-01-01&_sort=-authored

# Step 3: Find related encounters
GET /Encounter?patient=Patient/patient-123&date=2024-01-15
  • Patient - The patient who completed the questionnaire
  • Practitioner - Healthcare provider who administered or reviewed the questionnaire
  • Encounter - Healthcare encounter during which the questionnaire was completed
  • Questionnaire - The original questionnaire template that was completed

Include Parameters​

Use _include and _revinclude to fetch related resources:

# Get questionnaire response with patient details
GET /QuestionnaireResponse?patient=Patient/patient-123&_include=QuestionnaireResponse:patient

# Get questionnaire response with encounter details
GET /QuestionnaireResponse?patient=Patient/patient-123&_include=QuestionnaireResponse:encounter

Error Handling​

The QuestionnaireResponse resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

QuestionnaireResponse-Specific Error Scenarios​

  • 404 Not Found: QuestionnaireResponse ID doesn't exist or is not accessible
  • 400 Bad Request: Invalid search parameters or malformed date formats
  • Empty Results: No questionnaire responses match the search criteria

Troubleshooting Tips​

  • No Results for Patient: Verify patient ID exists and has completed questionnaires
  • Date Format Issues: Ensure authored dates are in YYYY-MM-DD format
  • Status Problems: Use valid status values (in-progress, completed, amended, entered-in-error, stopped)
  • Performance Issues: Use _count parameter to limit result sets

Supported Profiles​