REST API
Resources
Survey Tasks API
The survey tasks API allows you to get information about what survey tasks have been assigned to your participants, and to assign new tasks.
Survey Task Object
The basic survey task object is used in several of the API calls.
Unique identifier for the task.
The internal ID for the participant associated with this task.
Project-specific participant identifier for the participant associated with this task.
Participant identifier used to complete surveys via link, if that feature is enabled for the project.
Identifier for the survey the task is associated with.
The name of the survey the task is associated with.
The survey’s category, if set.
The participant-visible name of the survey the task is associated with.
The survey’s description.
When the participant started the task (or null if not yet started), in ISO8601 format
When the participant completed the task (or null if not yet completed), in ISO8601 format
Task status: closed, incomplete, or complete.
Whether the participant has started then exited the task, saving their progress.
The date when the task is/was due, in ISO8601 format
The date the task was created, in ISO8601 format
The date the task was last modified, in ISO8601 format
{
"id": "a88b43ff-b65b-4b35-af06-c9058829029b",
"participantID": "63dd6bf7-81d3-48c5-85fb-5c4666303acb",
"participantIdentifier": "58c2ab5d-4b73-4975-9599-a086fc78ca3f",
"linkIdentifier": "e22027a8-9bfa-46e7-ba13-e131245ea0e3",
"surveyID": "9af89352-09c2-4b28-be04-b6cc627628e1",
"surveyName": "Sleep Quality",
"surveyCategory": "Daily",
"surveyDisplayName": "Sleep Quality",
"surveyDescription": "",
"startDate":"2020-10-22T09:11:23-05:00",
"endDate":"2020-11-22T09:12:00-05:00",
"status": "incomplete",
"hasSavedProgress": false,
"dueDate": "2020-11-13T11:00:26.091+00:00",
"insertedDate": "2020-10-30T11:00:26.76Z",
"modifiedDate": "2020-11-13T12:00:16.343Z"
}{
"id": "a88b43ff-b65b-4b35-af06-c9058829029b",
"participantID": "63dd6bf7-81d3-48c5-85fb-5c4666303acb",
"participantIdentifier": "58c2ab5d-4b73-4975-9599-a086fc78ca3f",
"linkIdentifier": "e22027a8-9bfa-46e7-ba13-e131245ea0e3",
"surveyID": "9af89352-09c2-4b28-be04-b6cc627628e1",
"surveyName": "Sleep Quality",
"surveyCategory": "Daily",
"surveyDisplayName": "Sleep Quality",
"surveyDescription": "",
"startDate":"2020-10-22T09:11:23-05:00",
"endDate":"2020-11-22T09:12:00-05:00",
"status": "incomplete",
"hasSavedProgress": false,
"dueDate": "2020-11-13T11:00:26.091+00:00",
"insertedDate": "2020-10-30T11:00:26.76Z",
"modifiedDate": "2020-11-13T12:00:16.343Z"
}
Query Survey Tasks
GET /api/v1/administration/projects/:projectId/surveytasks?surveyName=SleepTime&status=incomplete
Query Parameters
Search for tasks for a participant based on the participant’s internal ID field.
Search for tasks for a participant based on the project-specific participant identifier.
Search for tasks with a particular status: closed, incomplete, or complete. You can specify multiple status values, separated by a comma (e.g. ?status=incomplete,complete).
Search for tasks from a particular survey, by identifier.
Search for tasks from a particular survey, by name. You can specify multiple names, separated by a comma (e.g. ?surveyName=Survey1,Survey2).
Search for tasks associated with a participant’s link identifier.
Search for tasks due after a specific date, in ISO8601 format.
Search for tasks due before a specific date, in ISO8601 format.
Search for tasks submitted to the system after a specific date, in ISO8601 format.
Search for tasks submitted to the system before a specific date, in ISO8601 format.
Specifies how the results will be sorted (by date inserted): Asecnding or Descending.
When the results span multiple pages, this specifies which page to retrieve. Null (the default) will retrieve the first page of results. For subsequent pages, use the ‘nextPageID’ from the response.
Limits the number of tasks returned.
Response Fields
A list of the survey tasks.
Unique identifier for the task.
The internal ID for the participant associated with this task.
Project-specific participant identifier for the participant associated with this task.
Participant identifier used to complete surveys via link, if that feature is enabled for the project.
Identifier for the survey the task is associated with.
The name of the survey the task is associated with.
The survey’s category, if set.
The participant-visible name of the survey the task is associated with.
The survey’s description.
When the participant started the task (or null if not yet started), in ISO8601 format
When the participant completed the task (or null if not yet completed), in ISO8601 format
Task status: closed, incomplete, or complete.
Whether the participant has started then exited the task, saving their progress.
The date when the task is/was due, in ISO8601 format
The date the task was created, in ISO8601 format
The date the task was last modified, in ISO8601 format
Identifier that you can use to retrieve the next page of results.
{
"nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
"surveyTasks": [
{
"id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
"surveyName": "Sleep Quality",
"status": "incomplete",
..,.
},
{
"id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
"surveyName": "Sleep Time",
"status": "complete",
...
}
]
}{
"nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
"surveyTasks": [
{
"id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
"surveyName": "Sleep Quality",
"status": "incomplete",
..,.
},
{
"id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
"surveyName": "Sleep Time",
"status": "complete",
...
}
]
}
Update Task
PUT /api/v1/administration/projects/:projectId/surveytasks/:taskId
The update task API only allows you to mark incomplete tasks as closed or complete. You cannot change anything else about the task data, and you cannot mark a task as incomplete or change an already-completed or closed task.
Body Parameters
Task status: closed or complete.
Response Fields
None{
"status": "complete"
}{
"status": "complete"
}
Bulk Add Tasks
POST /api/v1/administration/projects/:projectId/surveytasks
Body Parameters
A list of tasks to create, each containing the following fields:The internal ID of the participant the task should be assigned to. Either participantID or participantIdentifier is required to associate the task with a participant.
Project-specific participant identifier of the participant the task should be assigned to. Either participantID or participantIdentifier is required to associate the task with a participant.
The survey name that you wish to assign.
When the survey is due. Units are determined by dueAfterIntervalType.
The units for dueAfterIntervalAmount. May be Days, Weeks, Months, or Years.
Response Fields
None[
{
"participantID": "3a713a06-295d-4803-9602-776f09a1483b",
"surveyName": "Sleep Time",
"dueAfterIntervalAmount": 7,
"dueAfterIntervalType": "Days"
},
{
"participantID": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
"surveyName": "Sleep Quality",
"dueAfterIntervalAmount": 4,
"dueAfterIntervalType": "Weeks"
},
...
][
{
"participantID": "3a713a06-295d-4803-9602-776f09a1483b",
"surveyName": "Sleep Time",
"dueAfterIntervalAmount": 7,
"dueAfterIntervalType": "Days"
},
{
"participantID": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
"surveyName": "Sleep Quality",
"dueAfterIntervalAmount": 4,
"dueAfterIntervalType": "Weeks"
},
...
]
