Ga naar inhoud
RoQua LogoRoQua Documentatie

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

Section titled “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

Section titled “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 Deprecated. Only return responses whose completer_type equals the given value. Use respondent_id instead.
respondent_id integer Only return responses belonging to the given respondent.
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

Section titled “Response”

Sample request

HTTP Request
GET /api/v1/dossiers/epd_id_index/responses HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
[
  {
    "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

Section titled “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

Section titled “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

Section titled “Requesters”
Name Type Description
epd_id string The identifier for this professional given by the EPD during single sign-on.

Store a new response

Section titled “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

Section titled “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_type string [‘patient’(default) | ‘profess’] String identifying the respondent which filled out the questionnaire.
respondent string Deprecated. Alias for respondent_type.
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

Section titled “Response”

The created response is returned. See the section on listing all responses for an explanation of the response object attribute fields.

Sample request

HTTP Request
POST /api/v1/dossiers/epd_id_resp_create/responses HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN


{
  "questionnaire_key": "key_resp_cre",
  "answer_data": {
    "answer": "data"
  },
  "respondent": "patient",
  "started_at": 1422706855,
  "filled_out_at": 1422707455
}
{
  "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

Section titled “When no questionnaire exists for the questionnaire_key provided”

Sample request

HTTP Request
POST /api/v1/dossiers/:dossier_id/responses HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

Update a response

Section titled “Update 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

Section titled “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

Section titled “Response”

The created response is returned. See the section on listing all responses for an explanation of the response object attribute fields.

Sample request

HTTP Request
PUT /api/v1/dossiers/epd_id_resp_update/responses/5 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN


{
  "questionnaire_key": "key_resp_upd",
  "answer_data": {
    "answer": "data"
  }
}
{
  "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

Section titled “When the response already stores data updating is not allowed”

Sample request

HTTP Request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

When no response exists for the id provided

Section titled “When no response exists for the id provided”

Sample request

HTTP Request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

When no questionnaire exists for the questionnaire_key provided

Section titled “When no questionnaire exists for the questionnaire_key provided”

Sample request

HTTP Request
PUT /api/v1/dossiers/:dossier_id/responses/:external_id HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

Delete a response

Section titled “Delete 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

HTTP Request
DELETE /api/v1/dossiers/:dossier_id/responses/:external_id HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN