The survey tasks API allows you to get information about what survey tasks have been assigned to your participants, and to assign new tasks.
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 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",
"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",
"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"
}
GET /api/v1/administration/projects/:projectId/surveytasks?surveyName=SleepTime&status=incomplete
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.
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.
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 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",
...
}
]
}
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.
Task status: closed or complete.
{
"status": "complete"
}
{
"status": "complete"
}
POST /api/v1/administration/projects/:projectId/surveytasks
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.
[
{
"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"
},
...
]