Questionnaire

Last updated: 29 Jan 2025

A structured set of questions intended to guide the collection of answers from end-users. Questionnaires provide detailed control over order, presentation, phraseology and grouping to allow coherent, consistent data collection.

https://hl7.org/fhir/R4/questionnaire.html

See our article for information about how to create and upload a questionnaire in Canvas.

Understanding Canvas Questionnaires

Codings

All questionnaires must have coding, and all response options within a question on a questionnaire must have codings.

Question Types

Canvas supports 3 different type of questions:

1. Multi select response questions are denoted with:
"type": "choice", "repeats": true

2. Single select response questions are denoted with:
"type": "choice", "repeats": false

3. Free text response questions are denoted with:
"type": "text", "repeats": false

Questions can be reused in multiple questionnaires, but any given question code should only appear once within a particular questionnaire.

Endpoints

get

/Questionnaire/{id}

Questionnaire read

Read an Questionnaire resource.

Path Parameters

id required

string

The unique identifier for the Questionnaire

Response Payload Attributes

resourceType

string

The FHIR Resource name.

string

The identifier of the Questionnaire.

name

string

Name for this questionnaire (computer friendly).

Canvas automatically versions questionnaires based on the name. Once a questionnaire is retired, you will see a version number next to the name (e.g PHQ-9 (v7))

status

enum [ active | retired ]

The status of this questionnaire. Enables tracking the life-cycle of the content.

description

string

Natural language description of the questionnaire. May contain markdown syntax.

code

array[json]

Concept that represents the overall questionnaire.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the questionnaire.

item

array[json]

Questions and sections within the Questionnaire.

Click to view child attributes

linkId

string

Unique id for item in questionnaire.

code

array[json]

Corresponding concept for this item in a terminology.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the question.

text

string

Primary text for the item.

type

string

The type of questionnaire item this is.

Value Options Supported:

choice (for multiple or single choice questions)
text (for free text questions)

repeats

boolean

Whether the item may repeat. This value will be true for multiple choice questions and false for single select questions.

answerOptions

array[json]

Permitted answers

Click to view child attributes

valueCoding

json

Answer value.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the answer.

display

string

The display name of the coding.

Responses

200 OK

Request was successful.

Errors

401 Unauthorized

The request requires user authentication.

403 Forbidden

The request requires user authorization.

404 Not Found

The requested resource was not found.

get

/Questionnaire

Questionnaire search

Search for Questionnaire resources.

Query Parameters

_id

string

The identifier of the Questionnaire.

code

string

A code that corresponds to one of its items in the questionnaire.

A Questionnaire search of the form /Questionnaire?code=456789 will return Questionnaire resources uploaded to Canvas that have a question with the code 456789.

name

string

Computationally friendly name of the questionnaire

questionnaire-code

string

The questionnaire the answers are provided for.

A Questionnaire search of of the form /Questionnaire?questionnaire-code=711013002 will return Questionnaire resources uploaded to Canvas that have the code 711013002.

status

string

The current status of the questionnaire

Response Payload Attributes

resourceType

string

The FHIR Resource name.

type

string

This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .

total

integer

The number of resources that match the search parameter.

link

array[json]

Attributes relevant to pagination, see our Pagination page for more detail.

Click to view child attributes

relation

enum [self|first|next|last]

The relation of the page search

url

The search url for the specific relation

entry

array[json]

The results bundle that lists out each object returned in the search

Click to view child attributes

resource

json

The attributes specific to the resource type, see the Attributes section below

Attributes

resourceType

string

The FHIR Resource name.

string

The identifier of the Questionnaire.

name

string

status

enum [ active | retired ]

The status of this questionnaire. Enables tracking the life-cycle of the content.

description

string

Natural language description of the questionnaire. May contain markdown syntax.

code

array[json]

Concept that represents the overall questionnaire.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the questionnaire.

item

array[json]

Questions and sections within the Questionnaire.

Click to view child attributes

linkId

string

Unique id for item in questionnaire.

code

array[json]

Corresponding concept for this item in a terminology.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the question.

text

string

Primary text for the item.

type

string

The type of questionnaire item this is.

Value Options Supported:

choice (for multiple or single choice questions)
text (for free text questions)

repeats

boolean

Whether the item may repeat. This value will be true for multiple choice questions and false for single select questions.

answerOptions

array[json]

Permitted answers

Click to view child attributes

valueCoding

json

Answer value.

Click to view child attributes

system

string

The system url of the coding.

Value Options Supported:

http://loinc.org
http://snomed.info/sct
http://canvasmedical.com
http://www.ama-assn.org/go/cpt
http://hl7.org/fhir/sid/icd-10
http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal

code

string

The code of the answer.

display

string

The display name of the coding.

Responses

200 OK

Request was successful.

Errors

400 Bad Request

The request was invalid or cannot be otherwise served. An accompanying error message will explain further.

401 Unauthorized

The request requires user authentication.

403 Forbidden

The request requires user authorization.

curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/Questionnaire/<id>' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

import requests

url = "https://fumage-example.canvasmedical.com/Questionnaire/<id>"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
    "resourceType": "Questionnaire",
    "id": "47a408d7-9f1d-4cfd-97c7-aa810df9ed39",
    "name": "Exercise",
    "status": "active",
    "description": "No Description Provided",
    "code": [
        {
            "system": "http://snomed.info/sct",
            "code": "404684003"
        }
    ],
    "item": [
        {
            "linkId": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
            "code": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "228448000"
                }
            ],
            "text": "Do you exercise on a regular basis?",
            "type": "choice",
            "repeats": false,
            "answerOption": [
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "LA33-6",
                        "display": "Yes"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "LA32-8",
                        "display": "No"
                    }
                }
            ]
        },
        {
            "linkId": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
            "code": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "228449008"
                }
            ],
            "text": "In an average week, how many days do you exercise?",
            "type": "choice",
            "repeats": false,
            "answerOption": [
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "228449008-0",
                        "display": "0"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "38112003",
                        "display": "1"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "19338005",
                        "display": "2"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "79605009",
                        "display": "3"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "9362000",
                        "display": "4"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "34001005",
                        "display": "5"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "68244004",
                        "display": "6"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "65607009",
                        "display": "7"
                    }
                }
            ]
        },
        {
            "linkId": "93137723-295f-4b28-9f97-fb58825b2cda",
            "code": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "255257008"
                }
            ],
            "text": "On the days when you exercised, for how long did you exercise?",
            "type": "choice",
            "repeats": false,
            "answerOption": [
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "QUES_FINACIAL_STRESS_CODE_Q3_A1",
                        "display": "10-20 min"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "QUES_FINACIAL_STRESS_CODE_Q3_A2",
                        "display": "20-40 min"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "QUES_FINACIAL_STRESS_CODE_Q3_A3",
                        "display": "40-60 min"
                    }
                },
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "QUES_FINACIAL_STRESS_CODE_Q3_A4",
                        "display": "> 1 hr"
                    }
                }
            ]
        },
        {
            "linkId": "7eb053cd-cb2d-435f-8f55-f154645b55c4",
            "code": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "QUES_FINACIAL_STRESS_CODE_Q4"
                }
            ],
            "text": "What type of exercise do you do?",
            "type": "text",
            "repeats": false,
            "answerOption": [
                {
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "QUES_FINACIAL_STRESS_CODE_Q4_A1",
                        "display": "What type of exercise do you do?"
                    }
                }
            ]
        }
    ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Unknown Questionnaire resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
      }
    }
  ]
}

curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/Questionnaire?name=exercise' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

import requests

url = "https://fumage-example.canvasmedical.com/Questionnaire?name=exercise"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
        },
        {
            "relation": "first",
            "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
        },
        {
            "relation": "last",
            "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
        }
    ],
    "entry": [
        {
            "resource": {
                "resourceType": "Questionnaire",
                "id": "47a408d7-9f1d-4cfd-97c7-aa810df9ed39",
                "name": "Exercise",
                "status": "active",
                "description": "No Description Provided",
                "code": [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "404684003"
                    }
                ],
                "item": [
                    {
                        "linkId": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                        "code": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "228448000"
                            }
                        ],
                        "text": "Do you exercise on a regular basis?",
                        "type": "choice",
                        "repeats": false,
                        "answerOption": [
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "LA33-6",
                                    "display": "Yes"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "LA32-8",
                                    "display": "No"
                                }
                            }
                        ]
                    },
                    {
                        "linkId": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
                        "code": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "228449008"
                            }
                        ],
                        "text": "In an average week, how many days do you exercise?",
                        "type": "choice",
                        "repeats": false,
                        "answerOption": [
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "228449008-0",
                                    "display": "0"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "38112003",
                                    "display": "1"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "19338005",
                                    "display": "2"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "79605009",
                                    "display": "3"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "9362000",
                                    "display": "4"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "34001005",
                                    "display": "5"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "68244004",
                                    "display": "6"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "65607009",
                                    "display": "7"
                                }
                            }
                        ]
                    },
                    {
                        "linkId": "93137723-295f-4b28-9f97-fb58825b2cda",
                        "code": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "255257008"
                            }
                        ],
                        "text": "On the days when you exercised, for how long did you exercise?",
                        "type": "choice",
                        "repeats": false,
                        "answerOption": [
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "QUES_FINACIAL_STRESS_CODE_Q3_A1",
                                    "display": "10-20 min"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "QUES_FINACIAL_STRESS_CODE_Q3_A2",
                                    "display": "20-40 min"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "QUES_FINACIAL_STRESS_CODE_Q3_A3",
                                    "display": "40-60 min"
                                }
                            },
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "QUES_FINACIAL_STRESS_CODE_Q3_A4",
                                    "display": "> 1 hr"
                                }
                            }
                        ]
                    },
                    {
                        "linkId": "7eb053cd-cb2d-435f-8f55-f154645b55c4",
                        "code": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "QUES_FINACIAL_STRESS_CODE_Q4"
                            }
                        ],
                        "text": "What type of exercise do you do?",
                        "type": "text",
                        "repeats": false,
                        "answerOption": [
                            {
                                "valueCoding": {
                                    "system": "http://snomed.info/sct",
                                    "code": "QUES_FINACIAL_STRESS_CODE_Q4_A1",
                                    "display": "What type of exercise do you do?"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad request"
      }
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}