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.

Contents

Survey Task Object
Query Survey Tasks
Update Task
Bulk Add 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

The internal, stable, unique ID for the participant associated with this task.

participantIdentifier string

Project-set, unique participant identifier for the participant associated with this task.

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.

surveyCategory string

The survey’s category, if set.

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

schedule

Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.

Child Fields

schedule.id guid

Unique identifier for the schedule.

schedule.name string

Schedule name.

schedule.category string

User-assigned category for the schedule (optional).

schedule.interval integer

How often the survey is delivered, based on the interval type. For example, if intervalType is Weeks and interval is 4, it means the survey repeats every 4 weeks. Will be null if the schedule does not repeat.

schedule.intervalType string

Units for interval. May be Days, Weeks, Months, or Years.

    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",
  "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",
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
}
  {
  "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",
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
}

Query Survey Tasks

GET /api/v1/administration/projects/:projectId/surveytasks

Query Parameters

participantID guid

Search for tasks for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for tasks for a participant based on the project-set, unique 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).

surveyCategory string

Search for tasks from a given survey category.

linkIdentifier guid

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

dueAfter date

Search for tasks due after a specific date, in ISO8601 format.

dueBefore date

Search for tasks due before a specific date, in ISO8601 format.

insertedAfter date

Search for tasks submitted to the system after a specific date, in ISO8601 format.

insertedBefore date

Search for tasks submitted to the system before a specific date, in ISO8601 format.

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.

Child Fields

surveyTasks.id guid

Unique identifier for the task.

surveyTasks.participantID guid

The internal, stable, unique ID for the participant associated with this task.

surveyTasks.participantIdentifier string

Project-set, unique participant identifier for the participant associated with this task.

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.surveyCategory string

The survey’s category, if set.

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

surveyTasks.schedule

Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.

Child Fields

surveyTasks.schedule.id guid

Unique identifier for the schedule.

surveyTasks.schedule.name string

Schedule name.

surveyTasks.schedule.category string

User-assigned category for the schedule (optional).

surveyTasks.schedule.interval integer

surveyTasks.schedule.intervalType string

Units for interval. May be Days, Weeks, Months, or Years.

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",
        ...
      }
  ]
}
  {
  "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"
}
  {
  "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 internal, stable, unique ID of the participant the task should be assigned to. Either participantID or participantIdentifier is required to associate the task with a participant.

participantIdentifier string

Project-set, unique participant identifier of the participant the task should be assigned to. 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. Defaults to 0 Days for a task due immediately. Pass null to both dueAfterIntervalAmount and dueAfterIntervalType for a task that has no due date.

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"
  },
  ...
]
  [ 
  {
  "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.