Survey Answers API

The survey answers API allows you to manage your participants. You can search for answers by participant, by survey, and more.

Survey Answer Object

The basic survey answer object includes all the details about an answer.

id guid

Unique identifier for the answer (answerId).

participantID guid

Internal. stable, unique ID for the participant answering the survey.

surveyResultID guid

Identifier for the survey result the answer is associated with.

surveyID guid

Identifier for the survey the answer is associated with.

surveyVersion integer

Which version of the survey was answered.

taskID guid

Identifier for the survey task the answer is associated with.

surveyName string

The name of the survey the answer is associated with.

surveyDisplayName string

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

date date

The date the answer was recorded, in ISO8601 format.

stepIdentifier string

The name of the step that the answer was in response to.

resultIdentifier string

For form steps, this identifies the form item. For other step types, it will be the same as the stepIdentifier.

answers collection

The answer itself. This is a list to support multiple-choice questions. Simple responses will be a list containing a single value.

schedule

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

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 Answer Data
{
  "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
  "participantID": "cceace1f-33ce-4c87-bcbb-93ccc5ea19cb",
  "surveyResultID": "230b27b1-df0d-441d-8485-a929cdf4895a",
  "surveyID": "083b44c8-4273-4ad5-9132-3dce126d5e62",
  "surveyVersion": 8,
  "taskID": "5a613cf2-97ee-4fca-b2f7-ea79c5d6d35e",
  "surveyName": "Sleep Time",
  "surveyDisplayName": "Sleep Time",
  "date": "2020-11-09T15:38:00.196-05:00",
  "stepIdentifier": "Sleep Hours",
  "resultIdentifier": "Sleep Hours",
  "answers": [
      "5"
  ],
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
}
{ "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae", "participantID": "cceace1f-33ce-4c87-bcbb-93ccc5ea19cb", "surveyResultID": "230b27b1-df0d-441d-8485-a929cdf4895a", "surveyID": "083b44c8-4273-4ad5-9132-3dce126d5e62", "surveyVersion": 8, "taskID": "5a613cf2-97ee-4fca-b2f7-ea79c5d6d35e", "surveyName": "Sleep Time", "surveyDisplayName": "Sleep Time", "date": "2020-11-09T15:38:00.196-05:00", "stepIdentifier": "Sleep Hours", "resultIdentifier": "Sleep Hours", "answers": [ "5" ], "schedule": { "id": "a843df73-07c2-45a3-9808-98745fafc766", "name": "Weekly", "category": "Phase 1", "interval": 1, "intervalType": "Week" } }

Query Survey Answers

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

The survey answers query supports two different date queries: before/after and insertedBefore/After. The former queries use the date the answer was recorded by the participant; the latter ones use the date the answer was submitted to the system. The dates may be appreciably different if the participant started a survey, answered a few questions, and then submitted it much later. There may also be minor variations due to the participant’s device time compared to the server time. Use the insertedAfter query to search for new answers since a prior query.

Query Parameters

participantID guid

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

participantIdentifier string

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

surveyResultID guid

Search for answers from a particular survey result.

surveyName string

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

after date

Search for answers recorded by the participant after a specific date, in ISO8601 format.

before date

Search for answers recorded by the participant before a specific date, in ISO8601 format.

insertedAfter date

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

insertedBefore date

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

stepIdentifier string

Search for answers from a particular survey step, based on the step identifier (name). You can include multiple step identifiers, separated by a comma (e.g. ?stepIdentifier=Step1,Step2).

resultIdentifier string

Search for answers from a particular item within a form step. You can include multiple result identifiers, separated by a comma (e.g. ?resultIdentifier=Result1,Result2).

answer string

Search for specific answers. You can include multiple answers, separated by a comma (e.g. ?answer=Answer1,Answer2).

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

Response Fields

surveyAnswers collection

A list of the survey answers.

surveyAnswers.id guid

Unique identifier for the answer (answerId).

surveyAnswers.participantID guid

Internal. stable, unique ID for the participant answering the survey.

surveyAnswers.surveyResultID guid

Identifier for the survey result the answer is associated with.

surveyAnswers.surveyID guid

Identifier for the survey the answer is associated with.

surveyAnswers.surveyVersion integer

Which version of the survey was answered.

surveyAnswers.taskID guid

Identifier for the survey task the answer is associated with.

surveyAnswers.surveyName string

The name of the survey the answer is associated with.

surveyAnswers.surveyDisplayName string

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

surveyAnswers.date date

The date the answer was recorded, in ISO8601 format.

surveyAnswers.stepIdentifier string

The name of the step that the answer was in response to.

surveyAnswers.resultIdentifier string

For form steps, this identifies the form item. For other step types, it will be the same as the stepIdentifier.

surveyAnswers.answers collection

The answer itself. This is a list to support multiple-choice questions. Simple responses will be a list containing a single value.

surveyAnswers.schedule

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

surveyAnswers.schedule.id guid

Unique identifier for the schedule.

surveyAnswers.schedule.name string

Schedule name.

surveyAnswers.schedule.category string

User-assigned category for the schedule (optional).

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

surveyAnswers.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",
  "surveyAnswers": [
      {
          "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
          ..,.
      },
      {
        "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
        ...
      }
  ]
}
{ "nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de", "surveyAnswers": [ { "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae", ..,. }, { "id": "f716b2c5-980d-484f-a4b4-8663e9acc506", ... } ] }
See Survey Answer Object for all answer fields.