QuestionnaireResponse

QuestionnaireResponses are an essential part of Atticus. On this page, we'll dive into the different QuestionnaireResponse endpoints you can use to manage responses programmatically. We'll look at how to query, create, update, and delete responses.

The QuestionnaireResponse model

The QuestionnaireResponse model contains all responded answers to a questionnaire.

Properties

The QuestionnaireResponse model conforms to the FHIR QuestionnaireResponse resource. The following properties are available:

Name
resourceType*
Type
'QuestionnaireResponse'
Description
The FHIR resource type. This must be set to 'QuestionnaireResponse'.
Name
questionnaire*
Type
Canonical
Description
A FHIR Canonical url to the corresponding questionnaire (the form definition). For questionnaires (='templates') designed in Atticus Designer, this url will start with http://templates.tiro.health/templates/. Optionally, a version can be specified by appending |<version> to the url. This allows you to specify a specific version of the questionnaire: http://templates.tiro.health/templates/unreadable-unique-id|1.0.1.
Name
identifier
Type
Identifier[]
Description
An array of Identifier objects for this questionnaire response. More information about identifiers in Atticus can be found here.
Name
status*
Type
enum
Description
The status of the response. Possible values are:
- in-progress (most common)
- completed (makes report read-only and triggers processing.) Currently not allowed for external systems.
Name
subject*
Type
Reference
Description
A FHIR Reference object to the patient that is the subject of the response.
Name
encounter
Type
Reference
Description
A FHIR Reference to the encounter to which this response is related.

POST/QuestionnaireResponse

Create a new QuestionnaireResponse

This endpoint allows you to create a new QuestionnaireResponse.

Request

POST

/QuestionnaireResponse

curl -X POST https://reports.tiro.health/fhir/r5/QuestionnaireResponse \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "QuestionnaireResponse",
    "questionnaire": "http://templates.tiro.health/templates/unreadable-unique-id|1",
    "status": "in-progress",
    "identifier": [
      {
        "system": "http://example.com/my-hospital-reports/,
        "value": "123"
      }
    ],
    "subject": {
      "reference": "Patient/123"
    },
    "encounter": {
      "reference": "Encounter/456"
    }
  }'

Response

{
  "resourceType": "QuestionnaireResponse",
  "id": "1",
  "questionnaire": "http://templates.tiro.health/templates/unreadable-unique-id|1.0.1",
  "status": "in-progress",
  "identifier": [
    {
      "system": "http://example.com/my-hospital-reports/",
      "value": "123"
    }
  ],
  "subject": {
    "reference": "Patient/123"
  },
  "encounter": {
    "reference": "Encounter/456"
  }
}

GET/QuestionnaireResponse/:id

Get an existing QuestionnaireResponse

This endpoint allows you to retrieve an existing QuestionnaireResponse by providing the QuestionnaireResponse id.

Request

GET

/QuestionnaireResponse/1

curl -G https://reports.tiro.health/fhir/r5/QuestionnaireResponse/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

Response

{
  "resourceType": "QuestionnaireResponse",
  "id": "1",
  "questionnaire": "http://templates.tiro.health/templates/unreadable-unique-id|1.0.1",
  "status": "in-progress",
  "identifier": [
    {
      "system": "http://example.com/my-hospital-reports/",
      "value": "123"
    }
  ],
  "subject": {
    "reference": "Patient/123"
  },
  "encounter": {
    "reference": "Encounter/456"
  }
}

DELETE/QuestionnaireResponse/:id

Delete an existing QuestionnaireResponse

This endpoint allows you to delete an existing QuestionnaireResponse by providing the QuestionnaireResponse id. Once a QuestionnaireResponse is deleted, it cannot be recovered.

Request

DELETE

/QuestionnaireResponse/1

curl -X DELETE https://reports.tiro.health/fhir/r5/QuestionnaireResponse/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

Response

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Successfully deleted QuestionnaireResponse/1"
    }
  ]
}

Special considerations in Response

A QuestionnaireResponse resource has some special headers and response body properties that you should be aware of.

Link header

When making GET, POST, or PUT requests to QuestionnaireResponse endpoints, the response includes a Link header with the URL to open the report form in the browser. The URL is specified with the relation edit-form. You can use this URL to redirect users to the web-based form editor.

Example response header for a QuestionnaireResponse with id 123:

Link: <https://app.tiro.health/filler/edit?response=QuestionnaireResponse/123>; rel="edit-form"

Versioning info

The questionnaire property of the response body contains the canonical reference to the corresponding questionnaire (the form definition). The full version is always appended in the response.

When sending a request with a partial version:

{
  "resourceType": "QuestionnaireResponse",
  //...
  "questionnaire": "http://templates.tiro.health/templates/unreadable-unique-id|1",
  //...
}

you will receive aresponse with a full version

{
  "resourceType": "QuestionnaireResponse",
  //...
  "questionnaire": "http://templates.tiro.health/templates/unreadable-unique-id|1.0.1",
  //...
}