Survey Results API (V2)

The survey results V2 API allows you to query for the results of completed surveys.

Note
There are currently two versions of the Survey Results API/SDK: V1 and V2. V2 groups survey results and survey answers together for easier parsing.

Contents

Survey Result Object (V2)
Query Survey Results

Survey Result Object (V2)

The basic survey result object is used in several of the API calls.

Tip
See Data Overview for important information about how survey tasks, results, and answers relate to one another.

participantID guid

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

participantIdentifier string

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

surveyID guid

Identifier for the survey the result is associated with.

surveyName string

The name of the survey the result is associated with.

taskID guid

The associated survey task.

event string

The associated survey event.

instance integer

Instance number for multi-entry surveys. See survey instances for details.

answers object

A list of key/value pairs where key is the result identifier and value is an array of answers.

answersByStep object

If includeAnswersByStep is true, this will show which step each answer is associated with. In other words, instead of resultId:answers, it would be resultId:stepId:answers.

insertedDate date

When the result was added to the system, in ISO8601 format.

modifiedDate date

When the result was last modified, in ISO8601 format.

insertedByUserType, modifiedByUserType string

Type of user that created/modified the survey result. Can be one of: Participant, Coordinator, ServiceAccount (for automated submissions).

insertedByUser, modifiedByUser string

The username of the user that created/modified the survey result. Only populated when user type is Coordinator.

insertedByUserFullName, modifiedByUserFullName string

The full name of the user that created/modified the survey result. Only populated when user type is Coordinator.

Sample Survey Result Data (V2)

    {
  "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
  "participantIdentifier": "PT-123",
  "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
  "surveyName": "Sleep Time",
  "taskID": "ff44d70c-5933-f111-ad62-0affe31b18e7",
  "event": "visit 1",
  "instance": 1,
  "answers": {
    "intro": [
      "complete"
    ],
    "sleepHours": [
      "4"
    ],
    "sleepQuality": [
      "2"
    ]
  },
  "insertedDate": "2026-04-08T10:48:19.555-04:00",
  "insertedByUserType": "Participant",
  "modifiedDate": "2026-04-08T10:48:33.187-04:00",
  "modifiedByUserType": "Participant"
}
  {
  "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
  "participantIdentifier": "PT-123",
  "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
  "surveyName": "Sleep Time",
  "taskID": "ff44d70c-5933-f111-ad62-0affe31b18e7",
  "event": "visit 1",
  "instance": 1,
  "answers": {
    "intro": [
      "complete"
    ],
    "sleepHours": [
      "4"
    ],
    "sleepQuality": [
      "2"
    ]
  },
  "insertedDate": "2026-04-08T10:48:19.555-04:00",
  "insertedByUserType": "Participant",
  "modifiedDate": "2026-04-08T10:48:33.187-04:00",
  "modifiedByUserType": "Participant"
}

Query Survey Results

GET /api/v2/administration/projects/:projectId/surveyResults

Query Parameters

participantID guid

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

participantIdentifier string

Search for results for a participant based on the project-set, unique participant identifier.

surveyID guid

Search for results from a particular survey, by identifier.

surveyName string

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

event string

Search for results associated with a survey event. You can search for multiple events using a comma-separated list.

instance integer

Instance number for multi-entry surveys. See survey instances for details.

resultIdentifier string

A comma-separated list of result identifiers to include in the output.

insertedAfter date

Search for results submitted to the system on or after a specific date, in ISO8601 format.

insertedBefore date

Search for results submitted to the system on or before a specific date, in ISO8601 format.

modifiedAfter date

Search for results modified on or after a specific date, in ISO8601 format.

modifiedBefore date

Search for results modified on or before a specific date, in ISO8601 format.

includeAnswersByStep boolean

If true, the output will include the answersByStep breakdown highlighting which step each answer is from. This is useful for form steps.

pageID string

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 results returned.

Response Fields

surveyResults collection

A list of the survey results.

Child Fields

surveyResults.participantID guid

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

surveyResults.participantIdentifier string

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

surveyResults.surveyID guid

Identifier for the survey the result is associated with.

surveyResults.surveyName string

The name of the survey the result is associated with.

surveyResults.taskID guid

The associated survey task.

surveyResults.event string

The associated survey event.

surveyResults.instance integer

Instance number for multi-entry surveys. See survey instances for details.

surveyResults.answers object

A list of key/value pairs where key is the result identifier and value is an array of answers.

surveyResults.answersByStep object

If includeAnswersByStep is true, this will show which step each answer is associated with. In other words, instead of resultId:answers, it would be resultId:stepId:answers.

surveyResults.insertedDate date

When the result was added to the system, in ISO8601 format.

surveyResults.modifiedDate date

When the result was last modified, in ISO8601 format.

surveyResults.insertedByUserType, modifiedByUserType string

Type of user that created/modified the survey result. Can be one of: Participant, Coordinator, ServiceAccount (for automated submissions).

surveyResults.insertedByUser, modifiedByUser string

The username of the user that created/modified the survey result. Only populated when user type is Coordinator.

surveyResults.insertedByUserFullName, modifiedByUserFullName string

The full name of the user that created/modified the survey result. Only populated when user type is Coordinator.

nextPageID string

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

Sample Response

    {
  "nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
  "surveyResults": [
    {
      "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
      "participantIdentifier": "PT-123",
      "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
      "surveyName": "Sleep Time",
      "taskID": "ff44d70c-5933-f111-ad62-0affe31b18e7",
      ...
    },
    {
      "participantID": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "participantIdentifier": "PT-345",
      "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
      "surveyName": "Sleep Quality",
      "taskID": "76638d17-bd90-4bd4-b250-b91ca59edccb",
      ...
    },
    ...
  ]
}
  {
  "nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
  "surveyResults": [
    {
      "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
      "participantIdentifier": "PT-123",
      "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
      "surveyName": "Sleep Time",
      "taskID": "ff44d70c-5933-f111-ad62-0affe31b18e7",
      ...
    },
    {
      "participantID": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "participantIdentifier": "PT-345",
      "surveyID": "ac0bbc66-7914-ef11-aad6-0afb9334277d",
      "surveyName": "Sleep Quality",
      "taskID": "76638d17-bd90-4bd4-b250-b91ca59edccb",
      ...
    },
    ...
  ]
}

See Survey Result Object for all task fields.