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.

id guid

Unique identifier for the task.

participantID guid

Corresponds to the participants globlaly unique, auto-generated identifier.

participantIdentifier string

Project-specific participant identifier.

linkIdentifier string

Participant identifier used to complete surveys via link, if that feature is enabled for the project.

surveyID guid

Identifier for the survey the task is associated with.

surveyName string

The name of the survey the task is associated with.

surveyDisplayName string

The participant-visible name of the survey the task is associated with.

surveyDescription string

The survey’s description.

startDate date

When the participant started the task (or null if not yet started), in ISO8601 format

endDate date

When the participant completed the task (or null if not yet completed), in ISO8601 format

status string

Task status: closed, incomplete, or complete.

hasSavedProgress boolean

Whether the participant has started then exited the task, saving their progress.

dueDate date

The date when the task is/was due, in ISO8601 format

insertedDate date

The date the task was created, in ISO8601 format

modifiedDate date

The date the task was last modified, in ISO8601 format

Sample Survey Task Data
{
  "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"
}
               
    

Query Survey Tasks

GET /api/v1/administration/projects/:projectId/surveytasks?surveyName=SleepTime&status=incomplete

Query Parameters

participantID guid

Search for tasks for a participant based on the participant’s internal ‘id’ field.

participantIdentifier string

Search for tasks for a participant based on the project-specific participant identifier.

status string

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).

surveyID

Search for tasks from a particular survey, by identifier.

surveyName string

Search for tasks from a particular survey, by name. You can specify multiple names, separated by a comma (e.g. ?surveyName=Survey1,Survey2).

linkIdentifier guid

Search for tasks associated with a participant’s link identifier.

sortOrder string

Specifies how the results will be sorted (by date inserted): Asecnding or Descending.

pageID guid

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.

limit integer

Limits the number of tasks returned.

Response Fields

surveyTasks collection

A list of the survey tasks.

surveyTasks.id guid

Unique identifier for the task.

surveyTasks.participantID guid

Corresponds to the participants globlaly unique, auto-generated identifier.

surveyTasks.participantIdentifier string

Project-specific participant identifier.

surveyTasks.linkIdentifier string

Participant identifier used to complete surveys via link, if that feature is enabled for the project.

surveyTasks.surveyID guid

Identifier for the survey the task is associated with.

surveyTasks.surveyName string

The name of the survey the task is associated with.

surveyTasks.surveyDisplayName string

The participant-visible name of the survey the task is associated with.

surveyTasks.surveyDescription string

The survey’s description.

surveyTasks.startDate date

When the participant started the task (or null if not yet started), in ISO8601 format

surveyTasks.endDate date

When the participant completed the task (or null if not yet completed), in ISO8601 format

surveyTasks.status string

Task status: closed, incomplete, or complete.

surveyTasks.hasSavedProgress boolean

Whether the participant has started then exited the task, saving their progress.

surveyTasks.dueDate date

The date when the task is/was due, in ISO8601 format

surveyTasks.insertedDate date

The date the task was created, in ISO8601 format

surveyTasks.modifiedDate date

The date the task was last modified, in ISO8601 format

nextPageId

Identifier that you can use to retrieve the next page of results.

Sample Response
{
  "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",
        ...
      }
  ]
}
               
    
See Survey Task Object for all task fields.

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

status string (required)

Task status: closed or complete.

Response Fields

None
Sample Body Parameters
{
  "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:
participantID guid

The participant you wish to assign the task to. Corresponds to the participants globlaly unique, auto-generated identifier. Either participantID or participantIdentifier is required to associate the task with a participant.

participantIdentifier string

Project-specific participant identifier. Either participantID or participantIdentifier is required to associate the task with a participant.

surveyName string (required)

The survey name that you wish to assign.

dueAfterIntervalAmount integer

When the survey is due. Units are determined by dueAfterIntervalType.

dueAfterIntervalType string

The units for dueAfterIntervalAmount. May be Days, Weeks, Months, or Years.

Response Fields

None
Sample Body Parameters
[ 
  {
  "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"
  },
  ...
]
               
    
See Survey Task Object for all task fields.