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 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.
{
"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"
]
}
Query Survey Answers
GET /api/v1/administration/projects/:projectId/surveyanswers?surveyName=SleepTime&stepIdentifier=SleepHours
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 ID field.
participantIdentifier
string
Search for answers for a participant based on the project-specific 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.
+ Child Fields
surveyAnswers.id
guid
Unique identifier for the answer (answerId).
surveyAnswers.participantID
guid
Internal 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.
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",
...
}
]
}