/data/activities/responses/batch/{batchId}

Get the status and download link of your batch activities export.

Note:

Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see API Access.

Prerequisite

Steps

Retrieve activity data from your download link by following these steps:

  1. Make a GET call to obtain the download link:

    https://api.{region}.alida.com/v2/applications/{communityApiKeyName}/data/activities/responses/batch/{batchId}

  2. Make a GET call to retrieve activity data from the download link in the data field:

    https://api.{region}.alida.com/v2/applications/{communityApiKeyName}/data/activities/responses/files/{fileId}

  3. In the Locations header, use the link to download the export file. Skip this step if the download link is automatically redirected to download the export file.
    Note: Streaming is a recommended method to extract large quantities of data without affecting memory or performance. Use any HTTP client capable of streaming and is compatible with the language you are using.

Resource URL

  1. /v2/applications/{communityApiKeyName}/data/activities/responses/batch/{batchId}
  2. /v2/applications/{communityApiKeyName}/data/activities/responses/files/{fileId}

Available methods

Method Description
1. GET Get the status and download link of the batch activity data export.
2. GET Get the exported activity data from the download link.

Available fields for 1. GET

Element Description
createDate The date and time in UTC when the export was created.
createdBy The GUID of the user who created the batch activity data export.
data The download link to the batch activity data export.
datasetId The GUID of the dataset (activity).
id The GUID of the batch activity data export.
lastUpdateDate The date and time in UTC when the export was last updated.
message
This element contains any error messages. Possible values are:
  • Error exporting survey data: Refers to errors when extracting survey responses.
  • Survey not found: Refers to errors when trying to export an unsupported activity.
    Note: Exporting activities is currently available only for Community surveys and power surveys.
status The current status of the export. Possible values are:
  • Pending
  • Executing
  • Succeeded
  • Failed
Example
{
    "id": <GUID of the batch>,
    "datasetId": <GUID of the dataset(activity)>,
    "status": <pending|executing|succeeded|failed>,
    "message": <any error messages>,
    "createDate": <date-time (UTC) of when this record got created>,
    "createdBy": <user context that created this record>,
    "lastUpdateDate": <date-time (UTC) of when this record got last updated>,
    "lastUpdatedBy": <user context that last updated this record>,
    "data": <link to the batch export>
}

Available fields from the JSON file

Table 1. Top-level elements
Element Description
datasetId The GUID of the dataset (activity).
definition Activity fields and field groups in the dataset.
exportDate The date and time when the export was started.
exportOptions Export parameters specified. Possible values are:
  • fieldIds: List of survey questions specified.
  • sinceDatetime: All new or updated responses that occurred on or after the specified date-time value.
  • untilDatetime: All new or updated responses that occurred before the specified date-time value.
Note: Activities exported can fall slightly outside of the date-time specified in sinceDatetime and untilDatetime because data is filtered using the lastSyncDate of the activity.
id

GUID of the batchId.

lastSyncDate The date and time when activity values were last synced.
records A list of participant responses.
Table 2. Elements under the fields attribute
Element Description
dataType The type of data answer values are stored as. Possible values are:
  • string: The value is stored as text.
  • double: The value is stored as numeric.
  • datetime: The value is stored as date-time.
  • identifier: The value is stored as a text identifier.
  • enum: Allows the choice of a single value from a list of possible values.
  • set: Allows the choice of multiple values from a list of possible values.

This element can be found under the property container type.

description The question text of a survey question.
id The field's GUID.
isRequired This element is returned as true if the question was specified as required during survey authoring. Otherwise, it is omitted.

This element can be found under the property container meta.

isSensitive The value determines whether the field contains sensitive data. Possible values are:
  • true
  • false
isSystem The value determines whether it is a system question. Possible values are:
  • true
  • false

This element can be found under the property container meta.

name The name of the survey question.
Note: The survey question name is appended if it is one of the following question types:
  • Grid questions are appended with the row name.
  • Choice questions with other-specify options are appended with the answer option name.

For more information, see Extract Activities.

values The options of a survey question.
Note: values are only applicable to enum and set data types.
  • id: The GUID of the answerId, otherwise known as the question option.
  • name: The text value of a question option.

This element can be found under the property container type.

visibility The visibility setting of the question. Possible values are:
  • active
  • hidden

This element can be found under the property container meta.

Table 3. Elements under the fieldGroups attribute
Element Description
description The question text of a survey question.

This element can be found under the property container meta.

fieldIds The list of field IDs included in the fieldgroup
id The field group's GUID.
name The name of the survey question associated with the field group.
Table 4. Elements under the records attribute
Element Description
fields
  • id: GUID that references the survey question.
  • values: Responses to the respective survey question, which can contain verbatim text or GUID(s) referring to existing answer elements.
lastUpdateDate The date and time in UTC when the activity record was last updated.
ownerId The GUID of the participant, otherwise known as the memberId.
Note: The response payload will only contain the selected survey questions, if you specified the parameters in /data/activities/{activityId}/responses/batch.
Example

A response payload for a Single Choice Grid question with three rows and four answer option columns: 

{
  "id": <GUID of export batch>,
  "datasetId": <GUID of the dataset (activity)>,
  "exportOptions": {
    "fieldIds": [
      <list of fieldIds (survey question IDs) to export>
    ],
    "sinceDatetime": <only responses recorded on or after this date-time (UTC) are exported>
    "untilDatetime": <only responses recorded before this date-time (UTC) are exported>
  },
  "exportDate": <date-time (UTC) when the export was initiated>,
  "lastSyncDate": <date-time (UTC) when the the activity values were last synced>,
  "definition": {
    "fields": [
      {
        "id": <GUID of the field corresponding to row 1>,
        "name": <question name followed by an underscore and text from row 1>,
        "type": {
          "dataType": <enum|string|double|datetime|identifier|set>,
          "values": [
            {
              "id": <GUID of column 1>,
              "name": <text from column 1>
            },
            {
              "id": <GUID of column 2>,
              "name": <text from column 2>
            },
            {
              "id": <GUID of column 3>,
              "name": <text from column 3>
            },
            {
              "id": <GUID of column 4>,
              "name": <text from column 4>
            }
          ]
        },
        "isSensitive": <true|false>,
        "meta": {
          "description": <question text>,
          "visibility": <active|hidden>,
          "isSystem": <true|false>,
          "isRequired": <true|(omitted)>
        }
      },
      {
        "id": <GUID of the field corresponding to row 2>,
        "name": <question name followed by an underscore and text from row 2>,
        "type": {
          "dataType": <enum|string|double|datetime|identifier|set>,
          "values": [
            {
              "id": <GUID of column 1>,
              "name": "<text from column 1>
            },
            {
              "id": <GUID of column 2>,
              "name": "<text from column 2>
            },
            {
              "id": <GUID of column 3>,
              "name": "<text from column 3>
            },
            {
              "id": <GUID of column 4>,
              "name": "<text from column 4>
            }
          ]
        },
        "isSensitive": <true|false>,
        "meta": {
          "description": <question text>,
          "visibility": <active|hidden>,
          "isSystem": <true|false>,
          "isRequired": <true|(omitted)>
        }
      },
      {
        "id": <GUID of the field corresponding to row 3>,
        "name": <question name followed by an underscore and text from row 3>,
        "type": {
          "dataType": <enum|string|double|datetime|identifier|set>,
          "values": [
            {
              "id": <GUID of column 1>,
              "name": "<text from column 1>
            },
            {
              "id": <GUID of column 2>",
              "name": "<text from column 2>
            },
            {
              "id": <GUID of column 3>",
              "name": "<text from column 3>
            },
            {
              "id": <GUID of column 4>,
              "name": <text from column 4>
            }
          ]
        },
        "isSensitive": "<true|false>",
        "meta": {
          "description": <question text>,
          "visibility": <active|hidden>,
          "isSystem": <true|false>,
          "isRequired": <true|(omitted)>
        }
      }
    ],
    "fieldGroups": [
      {
        "id": <GUID of the field group comprising fields>,
        "name": <question name>,
        "fieldIds": [
          <GUID of the field corresponding to row 1>,
          <GUID of the field corresponding to row 2>,
          <GUID of the field corresponding to row 3>
        ],
        "meta": {
          "description": <question text>,
          "isRequired": <true|(omitted)>
        }
      }
    ]
  },
  "records": [
    {
      "ownerId": <GUID of participant 1>,
      "lastUpdateDate": <date-time (UTC) when the response record was last updated>,
      "fields": [
        {
          "id": <GUID of the field (survey question)>,
          "values": [
            <GUIDs of question options answered by participant 1. Can be string|double|datetime|null>
          ]
        }
      ]
    },
    {
      "ownerId": <GUID of participant 2>,
      "lastUpdateDate": <date-time (UTC) when the response record was last updated>,
      "fields": [
        {
          "id": <GUID of the field (survey question)>,
          "values": [
            <GUIDs of question options answered by participant 2. Can be string|double|datetime|null>
          ]
        }
      ]
    }
  ]
}

Why certain responses are not recorded?

Note: In the records attribute, responses:
  • Are recorded as null when a participant skips a question in the survey by clicking Skip.
  • Are not recorded when a question is skipped because of survey logic or the participant drops off before answering the question.
Example

A survey with five questions is distributed. Depending on the participant's responses, the fields may not be recorded. Consider the following cases:

  • If a participant answers questions 1-2 and then closes the survey before question 3, the fields for question 3-5 are not recorded.
  • If a participant answers question 1 and skips question 2 because of survey logic, the field for question 2 is not recorded but other questions are.
  • If a participant decides to answer questions 1-2, skips question 3 by clicking Skip, and answers questions 4-5, the values for question 3 are displayed as null and the other questions are recorded.

In this example, a participant decides to answer questions 1-2, skips question 3 by clicking Skip and then drops off the survey before question 4. They will see something similar to: 

  "records": [
    {
      "ownerId": <GUID of participant>,
      "lastUpdateDate": <date-time (UTC) when the response record was last updated>,
      "fields": [
        {
          "id": <GUID of the field for survey question 1>,
          "values": [<GUIDs of question options answered by the participant. Can be string|double|datetime|null>, ...]
        },
        {
          "id": <GUID of the field for survey question 2>,
          "values": [<GUIDs of question options answered by the participant. Can be string|double|datetime|null>, ...]
        },
        {
          "id": <GUID of the field for survey question 3>,
          "values": null
        }
      ]
    },
    ...