Get the status and download link of your batch activities export.
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 Shared responsibility.
Prerequisite
Steps
Retrieve activity data from your download link by following these steps:
-
Make a GET call to obtain the download link:
https://api.{region}.alida.com/v2/applications/{communityApiKeyName}/data/activities/responses/batch/{batchId} -
Make a GET call to retrieve activity data from the download link in the
datafield:https://api.{region}.alida.com/v2/applications/{communityApiKeyName}/data/activities/responses/files/{fileId} - 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
-
/v2/applications/{communityApiKeyName}/data/activities/responses/batch/{batchId} -
/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:
|
status
|
The current status of the export. Possible
values are:
|
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
| 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:
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
|
lastSyncDate
|
The date and time when activity values were last synced. |
records
|
A list of participant responses. |
| Element | Description |
|---|---|
dataType
|
The type of data answer values are stored as.
Possible values are:
This element can be found under the property container
|
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
|
isSensitive
|
The value determines whether the field
contains sensitive data. Possible values are:
|
isSystem
|
The value determines whether it is a system
question. Possible values are:
This element can be found under the property container
|
name
|
The name of the survey question.
Note: The survey question name is appended if it is one of the
following question types:
For more information, see Extract Activities. |
values
|
The options of a survey question.
Note:
values are only applicable to
enum and
set data types.
This element can be found under the property container
|
visibility
|
The visibility setting of the question.
Possible values are:
This element can be found under the property container
|
| Element | Description |
|---|---|
description
|
The question text of a survey question.
This element can be found under the property container
|
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. |
| Element | Description |
|---|---|
fields
|
|
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.
|
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?
records attribute, responses:
- Are recorded as
nullwhen 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
nulland 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
}
]
},
...