Skip to content

API: Questions

Make sure to read the API Overview before reading this document.

Retrieving a List of Questions

Required Variables

Variable Description
section Must be set to questions.
action Must be set to retrieve.
api_key Must be set to your unique API key.

Optional Variables

Variable Description
question_id An integer or series of integers which specifies the question IDs that you wish to include in the list. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all questions. This parameter is set to all by default.

Response

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <count>1</count>
    <question id="1">
        <text>Would you like soda with your movie?</text>
        <type>option</type>
        <answer id="27">Yes</answer>
        <answer id="28">No</answer>
    </question>
</xml>

Creating a Question

Required Variables

Variable Description
section Must be set to questions.
action Must be set to create.
api_key Must be set to your unique API key.
question_text A string which specifies the text of your new question.

Optional Variables

Variable Description
question_type An enum type which specifies the type of question you want to create. If not specified the question type defaults to manual. A value that is not a recognised question type is also treated as manual: a misspelled type does not return an error, so check the type of the created question if you are unsure. See the list below for available question types.
question_type List

Note: To make questions of certain types usable (e.g. checkbox, dropdown, webcollect), you must use the question id returned in the result to add answer option(s) to your question.

  • barcode behaves like manual, with a barcode button next to the input field. The user can scan a barcode with the device's camera instead of typing the answer.
  • barcodemultiline behaves like manualmultiline, with a barcode button next to the input field. The user can scan a barcode with the device's camera instead of typing the answer.
  • barcodenumeric behaves like manualnumeric, with a barcode button next to the input field. The user can scan a barcode with the device's camera instead of typing the answer.
  • checkbox will create a Multiple Choice (Multiple Answer) question. The user will be able to choose as many of the answer options as you add to the question. Requires answer options.
  • dropboximage will prompt the user to take a photo or choose one from their device's gallery.
  • dropdown will create a Multiple Choice (Single Answer) question formatted as a dropdown menu, similar to the "select" HTML element. When the user taps the question, they will be presented with the native picker UI of the OS. Requires answer option.
  • gps will prompt the user to confirm their current location, as determined by the device's onboard GPS.
  • manual will create a Short Answer question. The user can manually answer with the device's keyboard.
  • manualmultiline will create a Short Answer question that accepts multiple lines of text. The user can manually answer with the device's keyboard.
  • manualnumeric will create a Short Answer question limited to numeric entry. The user can manually answer using the device's dial pad.
  • option will create a Multiple Choice (Single Answer) question. The user will be prompted to choose one of several options. Requires answer options.
  • webcollect will display your Custom Question in a Web View below your question_text. Requires answer option.

Response

If your question is successfully created, we will respond with raw XML containing a status of 1 and the numerical ID of your new question.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <id>1002</id>
</xml>

Editing a Question

question_text is required on every edit, unlike editing a user or a device. Send the question's current text if you are not changing it, or the request is rejected. Other variables you omit do not affect their settings.

A question's type cannot be changed after it is created: question_type is ignored on this action. To use a different type, create a new question and delete the old one.

Required Variables

Variable Description
section Must be set to questions.
action Must be set to update.
api_key Must be set to your unique API key.
question_id An integer which specifies the ID of the question you wish to edit. Omitting it returns error 133; a question that does not exist or does not belong to your account returns error 50.
question_text A string which specifies the text of the question. Required on every edit, even when you are only changing another variable. Omitting it returns error 259.

Optional Variables

Variable Description
external_id A string which specifies your own identifier for the question. It may contain only letters, numbers, underscores and hyphens; any other character returns error 2349.

Response

If the question you specified is successfully edited, we will respond with raw XML containing a status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>

Deleting a Question

Required Variables

Variable Description
section Must be set to questions.
action Must be set to delete.
api_key Must be set to your unique API key.
question_id An integer or series of integers which specifies the question IDs that you wish to include in the list. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all questions.

Response

If you have successfully deleted your question, we will respond with raw XML containing a status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>

Adding an Answer Option

Required Variables

Variable Description
section Must be set to questions.
action Must be set to addanswer.
api_key Must be set to your unique API key.
question_id An integer which specifies the numeric question ID you want to add an answer to. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all answers.
answer_text A string which specifies the answer text you want to add to the question.

Response

After we receive these variables, we will respond with raw XML containing an ID and status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <id>1</id>
</xml>

Deleting an Answer Option

Required Variables

Variable Description
section Must be set to questions.
action Must be set to deleteanswer.
api_key Must be set to your unique API key.
answer_id An integer or series of integers specifying the numerical IDs of the answers you want to remove from a question.

Response

After we receive these variables, we will respond with raw XML containing an ID and status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>