Responses
Responses are questionnaire completions, although they need not be filled out yet. Upon creating an invitation, responses for all selected questionnaires are created. At this point, the responses have status new. When the patient fills out the questionnaire for the answer, its status will change to completed.
List all responses for dossier
Requests for more detailed information about responses are namespaced under a specific dossier, which is the /api/v1/dossiers/DOSSIER_ID path. In this path DOSSIER_ID is the external identifier used by the EPD to represent this patient.
GET /api/v1/dossiers/:dossier_id/responses.json
Parameters
| Name | Type | Description |
|---|---|---|
questionnaire_keys | 'array of strings' | Only return responses on questionnaires whose key is listed |
completed_before | time | Only return responses filled out before the specified time |
completed_after | time | Only return responses filled out after the specified time |
respondent_type | string | Only return responses whose completer_type equals the given value |
status | string | ['completed', 'aborted', 'open', 'scheduled'] Only return responses whose status equals the given value |
protocol_subscription_id | string | Only return responses associated to the protocol subscription with the given id |
Response
Sample request
GET /api/v1/dossiers/epd_id_index/responses
Status: 200 OK[
{
"id": 2,
"respondent_id": 5,
"name": "Questionnaire With Flags",
"questionnaire_name": "Questionnaire With Flags",
"questionnaire_key": "quest1",
"open_from": null,
"open_till": null,
"requesters": [],
"completer_type": "patient",
"completed_at": null,
"status": "open",
"completing_url": "http://default.example.com/client/session/new?token=fedca987",
"values": {},
"outcome": {
"scores": {},
"action": null,
"alarm": null,
"attention": null,
"complete": null
},
"flags": {
"female": false,
"with_flags_hides_v_1_flag": true
},
"textvars": {},
"started_at": null,
"measurement_id": null,
"non_response_id": null
},
{
"id": 3,
"respondent_id": 5,
"name": "Questionnaire With Textvars",
"questionnaire_name": "Questionnaire With Textvars",
"questionnaire_key": "quest2",
"open_from": null,
"open_till": null,
"requesters": [],
"completer_type": "patient",
"completed_at": null,
"status": "open",
"completing_url": "http://default.example.com/client/session/new?token=fedca987",
"values": {},
"outcome": {
"scores": {},
"action": null,
"alarm": null,
"attention": null,
"complete": null
},
"flags": {},
"textvars": {
"with_textvars_var1": "{{with_textvars_var1}}",
"with_textvars_var2": "var2_default",
"with_textvars_var3": "var3_default"
},
"started_at": null,
"measurement_id": null,
"non_response_id": null
},
{
"id": 4,
"respondent_id": 5,
"name": "OQ-45",
"questionnaire_name": "OQ-45",
"questionnaire_key": "oq45",
"open_from": null,
"open_till": null,
"requesters": [
{
"epd_id": "epdid_0"
}
],
"completer_type": null,
"completed_at": "2015-01-27T13:30:55.000+01:00",
"status": "completed",
"completing_url": null,
"values": {
"v_1": 4,
"v_2": 3,
"v_3": 2,
"v_4": 3,
"v_5": 3,
"v_6": 2,
"v_7": 3,
"v_8": 4,
"v_9": 2,
"v_10": 2,
"v_11": 3,
"v_12": 4,
"v_13": 2,
"v_14": 3,
"v_15": 4,
"v_16": 2,
"v_18": 3,
"v_19": 4,
"v_20": 3,
"v_21": 2,
"v_22": 3,
"v_23": 4,
"v_24": 2,
"v_25": 3,
"v_26": 4,
"v_27": 3,
"v_28": 3,
"v_29": 2,
"v_30": 3,
"v_31": 4,
"v_32": 2,
"v_33": 3,
"v_34": 4,
"v_35": 2,
"v_36": 3,
"v_37": 4,
"v_38": 2,
"v_39": 3,
"v_40": 4,
"v_41": 4,
"v_42": 3,
"v_43": 2,
"v_44": 3,
"v_45": 3,
"v_46": 4
},
"outcome": {
"scores": {
"totaal": {
"score": true,
"label": "Totaal",
"value": 135,
"norm": ">= 55",
"interpretation": "Klinisch",
"tscore": 110,
"tscore_interpretation": "Zeer hoog",
"oru_flag": "HH",
"global": true,
"referenced_values": [
"v_1",
"v_2",
"v_3",
"v_4",
"v_5",
"v_6",
"v_7",
"v_8",
"v_9",
"v_10",
"v_11",
"v_12",
"v_13",
"v_14",
"v_15",
"v_16",
"v_18",
"v_19",
"v_20",
"v_21",
"v_22",
"v_23",
"v_24",
"v_25",
"v_26",
"v_27",
"v_28",
"v_29",
"v_30",
"v_31",
"v_32",
"v_33",
"v_34",
"v_35",
"v_36",
"v_37",
"v_38",
"v_39",
"v_40",
"v_41",
"v_42",
"v_43",
"v_44",
"v_45",
"v_46"
]
},
"psychisch": {
"score": true,
"label": "Psychisch Onwelbevinden",
"value": 74,
"norm": ">= 33",
"interpretation": "Klinisch",
"tscore": 102,
"tscore_interpretation": "Zeer hoog",
"oru_flag": "HH",
"referenced_values": [
"v_2",
"v_3",
"v_5",
"v_6",
"v_8",
"v_9",
"v_10",
"v_11",
"v_13",
"v_15",
"v_23",
"v_24",
"v_25",
"v_26",
"v_28",
"v_30",
"v_32",
"v_34",
"v_35",
"v_36",
"v_37",
"v_41",
"v_42",
"v_43",
"v_46"
]
},
"interpers": {
"score": true,
"label": "Interpersoonlijk Functioneren",
"value": 33,
"norm": ">= 12",
"interpretation": "Klinisch",
"tscore": 99,
"tscore_interpretation": "Zeer hoog",
"oru_flag": "HH",
"referenced_values": [
"v_1",
"v_7",
"v_16",
"v_18",
"v_19",
"v_20",
"v_21",
"v_27",
"v_31",
"v_38",
"v_44"
]
},
"sociaal": {
"score": true,
"label": "Sociale Rolvervulling",
"value": 28,
"norm": ">= 10",
"interpretation": "Klinisch",
"tscore": 116,
"tscore_interpretation": "Zeer hoog",
"oru_flag": "HH",
"referenced_values": [
"v_4",
"v_12",
"v_14",
"v_22",
"v_29",
"v_33",
"v_39",
"v_40",
"v_45"
]
}
},
"action": "alarm",
"alarm": [
"v_8",
"v_11",
"v_27",
"v_33",
"v_45"
],
"attention": [],
"complete": null
},
"flags": {},
"textvars": {},
"started_at": "2015-01-31T13:30:55.000+01:00",
"measurement_id": null,
"non_response_id": null
}
]
Response Attributes
| Name | Type | Description |
|---|---|---|
id | integer | Id uniquely identifying the reponse record. |
external_id | string | The ID provided when submitting this response via POST or PUT. Null if this response was created/completed via RoQua. |
respondent_id | integer | Id of respondent who the response belong to (not always the person who typed them into the system) |
completed_at | string | An ISO 8601 formatted string that indicates when the response was completed, or null if this response is not yet completed. |
completer_type | string | Describes who the response was prepared for, e.g. ad_hoc_professional for bulk versions of patient lists. Can be patient, ad_hoc_professional, parent, second_parent or teacher. More types might be added later, therefore it is advised that API consumers select the desired types, and not reject the undesired types. |
completing_url | string | The URL that can be visited to complete this (and possibly other) response(s). Will be null if response is already completed. |
flags | `hash | Hash of flag_name to boolean |
measurement_id | integer | The measurement this response was created from (leads to protocol) |
non_response_id | integer | Id of non_response this response belongs to. |
open_from | string | An ISO 8601 formatted string that indicates when the response becomes completable, or null if this response is not only completable within a specific time window. |
open_till | string | An ISO 8601 formatted string that indicates when the response expires and is no longer completable, or null if this response is not only completable within a specific time window. |
outcome | hash | Hash with various outcome elements. See below for more details. |
questionnaire_name | string | The name of the questionnaire that was filled out. |
questionnaire_key | string | Key uniquely identifying the questionnaire that was filled out. |
requesters | array | Array of objects identifying the professionals that requested this questionnaire to be completed. |
status | string | One of the following values:scheduled - This response is scheduled to be completed at a later time. Cannot be completed right now, and visiting its URL will not result in this response being presented. See open_from and open_till attributes for the time window when this response will be open.open - This response is completable right now.aborted - Filling out the questionnaire has been aborted.completed - This response has been completed. |
started_at | string | An ISO 8601 formatted string that indicates when the response was started being filled out, or null if this data is not available. |
textvars | hash | Hash of textvar_name to string |
values | hash | Hash with key value pairs for every question in the questionnaire. Will be empty when the response is not completed. |
name | string | The name of the response. Warning, this field is deprecated, use questionnaire_name instead |
Outcome
| Name | Type | Description |
|---|---|---|
scores | hash | Hash containing a hash for each calculated score, index on the score key. Each score contains a value entry when the score was calculated successfully and may contain extra key value pairs for interpretation and t-scores. See the outcome description of each questionnaire for more information on the calculated scores. |
action | string | ['attention', 'alarm'] Whether the calculated outcome requires extra attention or whether it is alarming. |
alarm | array | Array containing all question keys giving rise to the alarm flag. |
attention | array | Array containing all question keys giving rise to the attention flag. |
complete | string | String indicating the percentage a questionnaire has been completed. Either '100%' or null when a questionnaire is fully completed, depending on whether the questionnaire has a definition for 'completeness'. |
Requesters
| Name | Type | Description |
|---|---|---|
epd_id | string | The identifier for this professional given by the EPD during single sign-on. |
Store a new response
To store an externally captured response perform a POST request to the path beneath. The dossier_id in the path is the unique identifier of the dossier to store the response with.
POST /api/v1/dossiers/:dossier_id/responses/
Parameters
| Name | Type | Description |
|---|---|---|
questionnaire_key | string | [Required] Key uniquely identifying the questionnaire in the ROM application |
external_id | string | [Required] ID as managed by the external application that "owns" this response |
answer_data | hash | [Required] Hash storing the answered option key for every question key |
started_at | integer | The Unix time when the questionnaire was started being filled out (greater or equal to 31 december 1999) |
filled_out_at | integer | The Unix time when the questionnaire was filled out (greater or equal to 31 december 1999) |
respondent | string | ['patient'(default) | 'profess'] String identifying the respondent which filled out the questionnaire. |
entered_by | string | [Optional, blank means response was entered by the respondent themselves.] The user id of the professional that entered the response into the system. For responses that were not entered directly by the respondent. The user id should correspond to the user id of that professional that is used in the EPD SSO connection. In the case of a 'profess' respondent, the implication is that this professional was the evaluator/originator of the response data, but this is not a strict requirement. |
Response
The created response is returned. See the section on listing all responses for an explanation of the response object attribute fields.
Sample request
POST /api/v1/dossiers/epd_id_resp_create/responses
Status: 201 Created{
"id": 1,
"respondent_id": 4,
"name": null,
"questionnaire_name": null,
"questionnaire_key": "key_resp_cre",
"open_from": null,
"open_till": null,
"requesters": [],
"completer_type": "patient",
"completed_at": "2015-01-31T13:30:55.000+01:00",
"status": "completed",
"completing_url": null,
"values": {
"answer": "data"
},
"outcome": {
"scores": {
"tot": {
"score": true,
"label": "Totaalscore",
"value": 37,
"referenced_values": []
}
},
"action": null,
"alarm": null,
"attention": null,
"complete": null
},
"flags": {},
"textvars": {},
"started_at": "2015-01-31T13:20:55.000+01:00",
"measurement_id": null,
"non_response_id": null
}
When no questionnaire exists for the questionnaire_key provided
Sample request
POST /api/v1/dossiers/:dossier_id/responses
Status: 404 Not FoundUpdate a response
To store external data on an existent pending response perform a put request to the path beneath.
The :dossier_id in the path is the unique identifier of the dossier to store the response with.
The :external_id in the path is the same external_id as given to the POST API call.
PUT /api/v1/dossiers/:dossier_id/responses/:external_id
Parameters
| Name | Type | Description |
|---|---|---|
questionnaire_key | string | [Required] Key uniquely identifying the questionnaire in the ROM application |
answer_data | hash | [Required] Hash storing the answered option key for every question key |
started_at | integer | The Unix time when the questionnaire was started being filled out (greater or equal to 31 december 1999) |
filled_out_at | integer | The Unix time when the questionnaire was filled out (greater or equal to 31 december 1999) |
Response
The created response is returned. See the section on listing all responses for an explanation of the response object attribute fields.
Sample request
PUT /api/v1/dossiers/epd_id_resp_update/responses/5
Status: 200 OK{
"id": 5,
"respondent_id": null,
"name": null,
"questionnaire_name": null,
"questionnaire_key": "key_resp_upd",
"open_from": null,
"open_till": null,
"requesters": [],
"completer_type": null,
"completed_at": "2015-01-31T13:30:55.000+01:00",
"status": "completed",
"completing_url": null,
"values": {
"answer": "data"
},
"outcome": {
"scores": {
"tot": {
"score": true,
"label": "Totaalscore",
"value": 37,
"referenced_values": []
}
},
"action": null,
"alarm": null,
"attention": null,
"complete": null
},
"flags": {},
"textvars": {},
"started_at": null,
"measurement_id": null,
"non_response_id": null
}
When the response already stores data updating is not allowed
Sample request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id
Status: 403 ForbiddenWhen no response exists for the id provided
Sample request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id
Status: 404 Not FoundWhen no questionnaire exists for the questionnaire_key provided
Sample request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id
Status: 404 Not FoundDelete a response
Responses can only be deleted by external_id, and thus only responses that were originally uploaded via the API can be deleted.
Sample request
DELETE /api/v1/dossiers/:dossier_id/responses/:external_id
Status: 204 No Content