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.
Tip
See
Data Overview for important information about how survey tasks, results, and answers relate to one another.
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.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.
{
"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
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.
{
"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",
...
}
]
}