API documentation

Project JSON representation

Version 1.1 - November 2014

A project represents a version of an instrument. It contains an ordered series of items, separated into modules.

At the top level, the JSON representation of a project contains two keys:

  • version - a string representation of the API version. For example, "1.1".
  • data - an object containing the rest of the data of the project.

The data object contains the following keys:

  • uuid - a unique hexadecimal identifier for the project itself
  • name - the name given to the instrument by its creators
  • title - the project's display title, possibly including the string {{PROJECT_NAME}} (which should be replaced with the name at display time)
  • modules - an array of the modules in the instrument

Modules

A module is a discrete section of the instrument. There are several types of modules, detailed below. A module contains the following keys:

  • uuid - a unique hexadecimal identifier for the module
  • title - an optional title for the module
  • instruction_text - if present, a piece of text, in Markdown format, to be presented to the survey taker
  • consent_text - if present, a piece of text, in Markdown format, to be presented for the survey taker to give informed consent
  • items - if present, an array of items in this module
  • module_type - one of the following strings to identify the type of the module:
    • Intro - a module consisting of text (specified in either instruction_text or consent_text) to be shown to the user. If consent_text is specified, the user must give informed consent or opt out of the survey.
    • Demographics - a module containing demographic questions (in the items array)
    • PROItems - a module containing survey questions
    • ThankYou - a module consisting of text to be shown at the end of the survey

Items

A Demographics or PROItems module can contain any number of items, which should be presented in a particular order. There are several types of items, detailed below. An item contains the following keys:

  • uuid - a unique hexadecimal identifier for the item
  • instructions - optional, individual instructional text to be shown above the item, in Markdown format. If an item contains instructions, it must be presented separately from any other items. (This is in contrast to question_text, documented below in the Question structure.)
  • questions - an array of questions. Most item types contain a single question, but some, such as multi_item_matrix, can contain multiple questions. Some, such as instruction, contain none.
  • choices - an array of choices. Some items, such as multiple_choice items, contain choices, but most do not.
  • skip_logic_attributes - an array of skip logic rules, which are evaluated in order once this item has been answered, and may trigger changes in the survey items to come.
  • item_type - one of the following strings to identify the type of the item:
    • consent - a prompt for informed consent
    • instruction - instructional text to be presented to the survey taker
    • text - a text field into which the survey taker can type a response
    • multiple_choice - a question with several possible responses, represented as choices
    • date_picker - a question that asks survey takers to choose a date
    • multi_item_matrix - a container of questions with a common set of choices, which can be presented in a tabular format

Questions

Most types of items contain at least one question. All questions contain the following keys:

  • uuid - a unique hexadecimal identifier for the question
  • question_text - the text to be displayed for this question, in Markdown format

text questions can contain the following additional keys:

  • multiline - if true, the survey taker is presented with a multi-line text input; otherwise it is a single-line input
  • numeric - if true, the answer for this question should be interpreted as a number
  • numeric_min_value - if set, the answer for this question must be at least this value. Only valid if the question is numeric.
  • numeric_max_value - if set, the answer for this question must be at most this value. Only valid if the question is numeric.

multiple_choice questions can contain the following additional keys:

  • select_all - if true, the survey taker can select multiple responses for this question; otherwise they can only select one
  • other - if true, an "Other" option will be added as a choice, with a field to fill in
  • show_choice_descriptions - if true, the choice_description text will be shown alongside the choice_text
  • require_other_response - if true, the field on the "Other" option must be filled in if "Other" is selected. Only valid if other is true.
  • randomize_choice_order - if true, the order in which the choices are shown will be randomized per survey taker. Survey takers should still see an individualized, consistent ordering of choices, but this ordering will be randomly generated for them.
  • answers_in_dropdown - if true, the answers will appear in a select element. By default they will use radio buttons

date_picker questions can contain the following additional keys:

  • date_precision - the most precise component of date that should be asked: either "year", "month", or "day"

consent questions can contain the following additional keys:

  • consent_header - the heading shown above the informed consent text
  • consent_preamble - text to be shown above between the header and the informed consent text, in Markdown format
  • consent_text_non_us - the informed consent text to be shown for a survey taker outside the United States, in Markdown format
    • (Note: for survey takers inside the United States, the value of the question_text key, documenta above, is used as the informed consent text.)
  • consent_text_unknown - the informed consent text to be shown for a survey taker whose country is unknown, in Markdown format
  • consent_footer - text to be shown below the informed consent text, in Markdown format
  • consent_accept_text - the text to be used on the "Accept" button
  • consent_decline_text - the text to be used on the "Decline" button
  • consent_message_on_approval - if true, the survey taker should receive a copy of the informed consent form after giving their informed consent, either by email or some similar format

multi_item_matrix questions can contain the following additional keys:

  • show_choice_descriptions - if true, the choice_description text from the first question in the matrix will be shown in the choice headers along with the choice_text. (Therefore, this key can only be true for the first question in the multi_item_matrix.)

Choices

multiple_choice and multi_item_matrix items can contain choices. A choice contains the following keys:

  • choice_text - the text shown to the survey taker for this choice
  • choice_value - the value to be recorded when the survey taker selects this choice
  • choice_description - an optional piece of text to be shown alongside the choice_text. Only shown if show_choice_descriptions is true.

Skip logic rules

Items can contain one or more skip logic rules. These rules are evaluated in the order specified, and the first one that is satisfied will perform its specified actions. If no rules are satisfied, no special action will be taken.

A skip logic rule contains the following attributes:

  • skip_logic_queries - an array of queries, each containing the following keys:
    • query_precedence - either "and" or "or". If "and", all queries must be satisfied in order to satisfy the skip logic rule. If "or", at least one query must be satisfied in order to satisfy the skip logic rule.
    • query_type - currently, the only supported query type is "response_for". This query type checks the response for an already-answered item.
    • item_id - the uuid of an item from which the value to compare against should be taken. This could include multiple values, in the case of a multiple_choice question with select_all enabled.
    • value_type - one of the following strings:
    • is - the query is satisfied if all of the values taken from the survey response exactly match the query's value
    • is_not - the query is satisfied if none of the values taken from the survey response exactly match the query's value
    • is_between - the query is satisfied if all of the values taken from the survey response are between the query's start_value and end_value, using Ruby's Range#include? semantics
    • is_not_between - the query is satisfied if none of the values taken from the survey response are between the query's start_value and end_value, using Ruby's Range#include? semantics
    • is_greater_than - the query is satisfied if all of the values taken from the survey response are greater than the query's value
    • is_greater_than_or_equal_to - the query is satisfied if all of the values taken from the survey response are greater than or equal to the query's value
    • is_less_than - the query is satisfied if all of the values taken from the survey response are less than the query's value
    • is_less_than_or_equal_to - the query is satisfied if all of the values taken from the survey response are less than or equal to the query's value
    • includes_any_of - the query is satisfied if any of the values taken from the survey response equal any of the comma-separated values in the query's value
    • includes_all_of - the query is satisfied if the set of values taken from the survey response includes all of the comma-separated values in the query's value
    • includes_none_of - the query is satisfied if the set of values taken from the survey response does not include any of the comma-separated values in the query's value
    • value - the value used for the comparison in this query; see the value_types above for details on how each type uses this field
    • start_value - the lower bound used for is_between and is_not_between queries
    • end_value - the upper bound used for is_between and is_not_between queries
  • result_action - the action to be taken if the queries evaluate to true. One of the following strings:
    • jump_to_node - skip to the module or item specified in the result_args
    • turn_off_modules - for this survey taker, deactivate the modules specified in the result_args
    • end_current_module - skip to the next module in the survey
    • end_survey - skip all remaining modules and items in the survey and end the survey immediately
  • result_args - additional information depending on the result_action as follows:
    • For jump_to_node, a string containing the uuid of another module or item in the survey to jump to
    • For turn_off_modules, an array of strings containing the uuids of subsequent modules to deactivate for this survey taker