Respondent

NameDescriptionTypeAdditional information
RespondentId

Unique respondent number

integer

LanguageCode

2-letter ISO 639-1 language code

string

RespondentStatusId

The id shows the completion level: partial, reached end or screened out.

integer

3/lookup/respondentstatus

ResponseDate

Date Responded (in ISO 8601 format)

date

In case of an anonymous survey the time is reset to 00:00:00

,

Obsolete: This field will be replaced with DateResponded.

CompletionTime

Time (in seconds) spent completing the survey

integer

Not available for an anonymous survey

DistributionMethodId

The channel used to reach the survey e.g. email, SMS, etc.

integer

3/lookup/distribution

BrowserId

The id of the browser used to complete the survey

byte

3/lookup/browsers

OsId

The id of the operating system used to complete the survey

byte

3/lookup/os

IsMobile

Whether or not the respondent was using a mobile operating system to complete the survey

boolean

IpAddress

The IP address used to complete the survey

string

Not available for an anonymous survey

RespondentReportUrl

Url to the respondent’s answer summary webpage

string

ReportUrl

Url to the internal respondent's answer summary webpage

string

The report contains contactinformation and hidden questions.

EditUrl

This URL will allow you to change responses given to this survey.

string

Be sure you have permission from the respondent and you must respect the ICC/Esomar international code at all times. Learn more

Responses

All responses for this respondent. When retrieving a list of respondents, this property is by default not available. For instance if you are building an overview of respondents, you won't use the responses. If you would like this additional information, you can use the expand parameter expand=Responses.

Collection of Response

Expandable

Location

Location based on the IP address. When retrieving a list of respondents, this property is by default not available. If you would like this additional information, you can use the expand parameter expand=Location.

IPLocation

Expandable, not available for an anonymous survey

Score

The total score for this respondent: sum of all SurveyQuestionResponse.Value

decimal number

RespondentHash

The unique hash for this respondent, when using an external url in branching you should include and validate the respondent hash. The external url can be very useful when building custom respondent reports.

string

PanelistStatusId

Status of the panelist e.g. included, invited, bounced, etc. Learn more.

integer

3/lookup/paneliststatus

DateAdded

Date added to the survey

date

DateInvited

Date invitation has been sent

date

DateSawMail

Date the mail has been viewed

date

DateClickedThrough date

DateReminded

Date reminder has been sent

date

DateRemindedPartial

Date partial reminder has been sent

date

DateResponded

Date the panelist responded to the survey

date

Password

The password which respondents need to access the survey. This is only available if the distribution panel "Paper - with panel" is active.

string

DateSentThankYouMail

Date thank you mail has been sent

date

DateToBeInvited

Date invitation will be sent in case it's different then the DateAdded

date

ISO 8601 format

DateSecondReminder

Date second reminder has been sent

date

DateToExpire

Date the invitation will expire

date

ISO 8601 format

DateLastModified

Date and time that the panelist was last modified. This date only relates to the panelist information, not to contact/respondent data.

date

ISO 8601 format

ContactId

Unique contact number.

integer

FirstName

Contact’s first name.

string

Not available when retrieving respondents for an anonymous survey

LastName

Contact’s last name.

string

Not available when retrieving respondents for an anonymous survey

Email

Contact's email address.

string

Not available when retrieving respondents for an anonymous survey

LangCode

2-letter ISO 639-1 language code

string

CustomField1

A field which can be used to store additional contact information.

string

CustomField2

A field which can be used to store additional contact information.

string

CustomField3

A field which can be used to store additional contact information.

string

CustomField4

A field which can be used to store additional contact information.

string

CustomField5

A field which can be used to store additional contact information.

string

CustomField6

A field which can be used to store additional contact information.

string

CustomField7

A field which can be used to store additional contact information.

string

CustomField8

A field which can be used to store additional contact information.

string

CustomField9

A field which can be used to store additional contact information.

string

CustomField10

A field which can be used to store additional contact information.

string

CustomField11

A field which can be used to store additional contact information.

string

CustomField12

A field which can be used to store additional contact information.

string

CustomField13

A field which can be used to store additional contact information.

string

CustomField14

A field which can be used to store additional contact information.

string

CustomField15

A field which can be used to store additional contact information.

string

CustomField16

A field which can be used to store additional contact information.

string

CustomField17

A field which can be used to store additional contact information.

string

CustomField18

A field which can be used to store additional contact information.

string

CustomField19

A field which can be used to store additional contact information.

string

CustomField20

A field which can be used to store additional contact information.

string

Street

Contact's street name.

string

Not available when retrieving respondents for an anonymous survey

HouseNumber

Contact's house number.

string

Not available when retrieving respondents for an anonymous survey

Suite

Contact's apt. number.

string

Not available when retrieving respondents for an anonymous survey

PostalCode

Postal code.

string

City

Contact's city.

string

State

ISO 3166-2 two-last letters state code.

string

3/lookup/states

Province

Contact's procince.

string

Phone

Contact's phone number in the E.164 format (+[country code] [area code] [number])

string

Not available when retrieving respondents for an anonymous survey

CountryId

ISO 3166-1 two-letter country code.

string

3/lookup/countries

Gender

Contact's gender.

string

Matching regular expression pattern: ^[m|M|f|F]$

DateOfBirth

Contact's birthday.

date

* ISO 8601 format * Not available when retrieving respondents for an anonymous survey

IsBounced

Indicates if the email address for this contact is currently on the bounce list.

boolean

IsOptedOut

Indicates if this contact is currently on the opt out list.

boolean

Links

HATEOAS related to this object. It wil contain relevant url's such as previous and next page for paged results, create/update/delete action. These url's can be used in your application for the next steps in your application logic.

Hateoas

Related Methods

Verb Url Description
GET 3/surveys/{surveyId}/respondents?top={top}&skip={skip}&select={select}&filter={filter}&orderby={orderby}&expand={expand}

Retrieve all respondents from a survey which match the passed criteria. Use the expand=Responses parameter to immediately include the responses of a respondent.

GET 3/surveys/{surveyId}/respondents/{respondentId}

Get the respondent with responses from a survey.

POST webhooks/event/Respondent/Complete

Occurs when a respondent completes a survey.

POST webhooks/event/Respondent/PageSubmitted

Occurs for each page a respondent completes.