| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
Occurs the first time the API throttling limit is reached for your account. |
||||
| POST | webhooks/event/apirequest/throttlinglimitreached |
Occurs the first time the API throttling limit is reached for your account. |
||
ContactFolders are a way to structure your contact groups. They will appear in the tool as folders which contain the contact groups. A contact folders can have subfolder(s) and can contain contact group(s).
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
GET - 3/contactfolders
Retrieve all contacts folders which match the passed criteria
Required Roles
Contacts (read)
|
||||
|
PUT - 3/contactfolders/{id}
Update a contacts folder name by its id.
Required Roles
Contacts (write)
|
||||
|
DELETE - 3/contactfolders/{id}
Delete a contacts folder based on its id.
Required Roles
Contacts (write)
|
||||
| GET | 3/contactfolders |
Retrieve all contacts folders which match the passed criteria |
Contacts (read) |
|
| POST | 3/contactfolders |
Create a new contacts folder. |
Contacts (write) |
|
| GET | 3/contactfolders/{id} |
Retrieve a contact folder by id. |
Contacts (read) |
|
| PUT | 3/contactfolders/{id} |
Update a contacts folder name by its id. |
Contacts (write) |
|
| DELETE | 3/contactfolders/{id} |
Delete a contacts folder based on its id. |
Contacts (write) |
|
With these request you can manage your contacts. A contact must always be part of at least one contact groups. A contact group can exist without contacts. Contact groups can be structured in contacts folders.
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
GET - 3/contactgroups
Retrieve all contactgroups which match the passed criteria
Required Roles
Contacts (read)
Cached Time
1 minute
|
||||
|
Updates the contact group by its id.
Required Roles
Contacts (write)
|
||||
|
DELETE - 3/contactgroups/{groupid}
Delete a contactgroup by id. All contacts only linked to this group will also be deleted.
Required Roles
Contacts (write)
|
||||
|
Retrieve all contacts from a contact group which match the passed criteria.
Required Roles
Contacts (read)
|
||||
|
Add a contact to the contactgroup
Required Roles
Contacts (write)
|
||||
|
DELETE - 3/contactgroups/{groupid}/contacts
Remove all contacts from this group. If the contact is only linked to the indicated group, the contact will be removed completely. If the contact is linked to other contact groups, the contact will be removed from this group but he/she will remain in other groups.
Required Roles
Contacts (write)
|
||||
|
Add an existing contact to a contact group.
Required Roles
Contacts (write)
|
||||
|
Remove a contact by id. If the contact is only linked to the indicated group, the contact will be removed completely. If the contact is linked to other contact groups, the contact will be removed from this group but he/she will remain in other groups.
Required Roles
Contacts (write)
|
||||
| GET | 3/contactgroups |
Retrieve all contactgroups which match the passed criteria |
Contacts (read) |
1 minute |
| POST | 3/contactgroups |
Create a new contactgroup. |
Contacts (write) |
|
| GET | 3/contactgroups/{groupid} |
Retrieve a contact group by id. |
Contacts (read) |
|
| PUT | 3/contactgroups/{groupid} |
Updates the contact group by its id. |
Contacts (write) |
|
| DELETE | 3/contactgroups/{groupid} |
Delete a contactgroup by id. All contacts only linked to this group will also be deleted. |
Contacts (write) |
|
| GET | 3/contactgroups/{groupid}/contacts |
Retrieve all contacts from a contact group which match the passed criteria. |
Contacts (read) |
|
| POST | 3/contactgroups/{groupid}/contacts |
Add a contact to the contactgroup |
Contacts (write) |
|
| DELETE | 3/contactgroups/{groupid}/contacts |
Remove all contacts from this group. If the contact is only linked to the indicated group, the contact will be removed completely. If the contact is linked to other contact groups, the contact will be removed from this group but he/she will remain in other groups. |
Contacts (write) |
|
| PUT | 3/contactgroups/{groupid}/contacts/{contactid} |
Add an existing contact to a contact group. |
Contacts (write) |
|
| DELETE | 3/contactgroups/{groupid}/contacts/{contactid} |
Remove a contact by id. If the contact is only linked to the indicated group, the contact will be removed completely. If the contact is linked to other contact groups, the contact will be removed from this group but he/she will remain in other groups. |
Contacts (write) |
|
With these requests you can manage your contacts without a reference to a contactgroup.
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
GET - 3/contacts
Retrieve all contacts which match the passed criteria
Required Roles
Contacts (read)
Cached Time
10 minutes
|
||||
|
Import contacts in bulk. Depending on your import configuration you can receive a email notification on each import. You can also trace the item in the queue when requesting the result.
Required Roles
Contacts (write)
|
||||
|
Update an existing import configuration.
Required Roles
Contacts (write)
|
||||
|
Renames the import configuration.
Required Roles
Contacts (write)
|
||||
|
Remove a import configuration by id.
Required Roles
Contacts (write)
|
||||
|
Retrieve an existing import configuration by its id. |
||||
|
Retrieve all available options which you can use as TargetColumnName in the ImportColumnMapping.
Cached Time
1 day
|
||||
|
GET - 3/contacts/optouts
Retrieve the opt-out list of your account taking the passed criteria into account
Required Roles
Contacts (read)
|
||||
| GET | 3/contacts |
Retrieve all contacts which match the passed criteria |
Contacts (read) |
10 minutes |
| POST | 3/contacts |
Create a new contact in a survey |
Contacts (write) |
|
| POST | 3/contacts |
Create a new contact in a contact list |
Contacts (write) |
|
| GET | 3/contacts/{contactid} |
Retrieve a contact by id. |
Contacts (read) |
|
| PUT | 3/contacts/{contactid} |
Update a contact by id. |
Contacts (write) |
|
| DELETE | 3/contacts/{contactid} |
Remove a contact by id. |
Contacts (write) |
|
| POST | 3/contacts/import/{importconfigid} |
Import contacts in bulk. Depending on your import configuration you can receive a email notification on each import. You can also trace the item in the queue when requesting the result. |
Contacts (write) |
|
| GET | 3/contacts/import/{queueitemid} |
Get the result of an import. |
||
| POST | 3/contacts/import/configs |
Create a new import configuration. |
Contacts (write) |
|
| GET | 3/contacts/import/configs |
Retrieve the existing import configurations. |
||
| PUT | 3/contacts/import/configs/{importconfigid} |
Update an existing import configuration. |
Contacts (write) |
|
| PUT | 3/contacts/import/configs/{importconfigid} |
Renames the import configuration. |
Contacts (write) |
|
| DELETE | 3/contacts/import/configs/{importconfigid} |
Remove a import configuration by id. |
Contacts (write) |
|
| GET | 3/contacts/import/configs/{importconfigid} |
Retrieve an existing import configuration by its id. |
||
| GET | 3/contacts/import/result/{queueitemid} |
Get the result of an import. |
||
| GET | 3/contacts/import/targetcolumns |
Retrieve all available options which you can use as TargetColumnName in the ImportColumnMapping. |
1 day | |
| POST | 3/contacts/optouts |
Add new opt-outs for your account |
Contacts (write) |
|
| GET | 3/contacts/optouts |
Retrieve the opt-out list of your account taking the passed criteria into account |
Contacts (read) |
|
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
GET - 3
Default API-call which will return the urls to the root requests in the Links property.
Cached Time
1 day
|
||||
|
GET - 3/throttle
To check how your application behaves when running into a throttling exception, you can use this request to get the throttling exception. |
||||
| GET | 3 |
Default API-call which will return the urls to the root requests in the Links property. |
1 day | |
| GET | 3/throttle |
To check how your application behaves when running into a throttling exception, you can use this request to get the throttling exception. |
||
Create your webhooks with these rest requests and allow us to communicate with you. In short, these are our REST Hooks.
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
POST - 3/hooks
Create a new web hook. We will check your API key roles depending on the event used in the webhook. |
||||
|
POST - 3/hooks/{webhookid}/activate
Activate your webhook. Activation is required before you will receive requests. This flow is required to improve security. |
||||
|
Deactivate your webhook. You won't receive any request anymore. But the webhook ID and key will remain the same for Activation in the future. |
||||
|
GET - 3/hooks/{webhookid}/demo
Retrieve a demo object of the webhook you just created. The data returned in the demo is fixed and only depending on the type of event used in your webhook, it is not related to any survey, contact, respondent, ... in your account. |
||||
|
GET - 3/hooks/events
Retrieve the available events to which you can attach your web hooks.
Cached Time
1 day
|
||||
| GET | 3/hooks |
Retrieve all webhooks available for you. |
||
| POST | 3/hooks |
Create a new web hook. We will check your API key roles depending on the event used in the webhook. |
||
| GET | 3/hooks/{webhookid} |
Retrieve a webhook configuration by ID. |
||
| DELETE | 3/hooks/{webhookid} |
Remove the web hook. |
||
| POST | 3/hooks/{webhookid}/activate |
Activate your webhook. Activation is required before you will receive requests. This flow is required to improve security. |
||
| PUT | 3/hooks/{webhookid}/deactivate |
Deactivate your webhook. You won't receive any request anymore. But the webhook ID and key will remain the same for Activation in the future. |
||
| GET | 3/hooks/{webhookid}/demo |
Retrieve a demo object of the webhook you just created. The data returned in the demo is fixed and only depending on the type of event used in your webhook, it is not related to any survey, contact, respondent, ... in your account. |
||
| GET | 3/hooks/events |
Retrieve the available events to which you can attach your web hooks. |
1 day | |
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
| GET | 3/keys/current |
Get the roles related to the current key. |
||
To limit the size and redundancies of api responses, we use ids instead of text labels as much as possible. For example, when retrieving a list of respondents, the id instead of the name of the browser is returned. To know what the id stand for you can use the following lookup methods to retrieve a user-friendly name.
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
GET - 3/lookup
Retrieve an overview of available lookup calls to improve discoverability.
Cached Time
1 day
|
||||
|
GET - 3/lookup/browsers
Retrieve the browser id and browser names for all browsers which we identify when completing a survey. (only in English)
Cached Time
1 day
|
||||
|
GET - 3/lookup/contactstatus
Retrieve the contact status id and name for all possible contact statuses. The data will be retrieved in the requested language. The possible statuses are discussed in our knowledgebase.
Cached Time
1 day
|
||||
|
GET - 3/lookup/countries
Retrieve all ISO 3166-1 two-letter country code and country name. The data will be retrieved in the requested language.
Cached Time
1 day
|
||||
|
GET - 3/lookup/datatypes
Retrieve the id and name of all available data types. (only in English)
Cached Time
1 day
|
||||
|
GET - 3/lookup/distribution
Retrieve the distribution method id and names for the distribution methods we offer. The data will be retrieved in the requested language.
Cached Time
1 day
|
||||
|
Retrieve the list of import config update types
Cached Time
1 day
|
||||
|
GET - 3/lookup/os
Retrieve the os id and os name for all operating systems which we identify when completing a survey. (only in English)
Cached Time
1 day
|
||||
|
GET - 3/lookup/questiontypes
Retrieve the question type id and name for the question types. The data will be retrieved in the requested language.
Cached Time
1 day
|
||||
|
Retrieve respondent end status id and name for the respondent statuses. (only in English)
Cached Time
1 day
|
||||
|
GET - 3/lookup/resultcodes
Retrieve the list of ResultCodes which are returned when importing contacts or adding responses.
Cached Time
1 day
|
||||
|
GET - 3/lookup/scaletypes
Retrieve the scale type id and name of all possible scaletypes.
Cached Time
1 day
|
||||
|
GET - 3/lookup/states
Retrieve the ISO 3166-2 two-last letter state codes and name for all US states. (only in English)
Cached Time
1 day
|
||||
|
GET - 3/lookup/surveylanguages
Retrieve the list of languages which are support in the survey interface and can be used to when translating your survey.
Cached Time
1 day
|
||||
|
GET - 3/lookup/surveystatus
Retrieve the survey status id and name for all possible survey statuses. The data will be retrieved in the requested language.
Cached Time
1 day
|
||||
| GET | 3/lookup |
Retrieve an overview of available lookup calls to improve discoverability. |
1 day | |
| GET | 3/lookup/browsers |
Retrieve the browser id and browser names for all browsers which we identify when completing a survey. (only in English) |
1 day | |
| GET | 3/lookup/contactstatus |
Retrieve the contact status id and name for all possible contact statuses. The data will be retrieved in the requested language. The possible statuses are discussed in our knowledgebase. |
1 day | |
| GET | 3/lookup/countries |
Retrieve all ISO 3166-1 two-letter country code and country name. The data will be retrieved in the requested language. |
1 day | |
| GET | 3/lookup/datatypes |
Retrieve the id and name of all available data types. (only in English) |
1 day | |
| GET | 3/lookup/distribution |
Retrieve the distribution method id and names for the distribution methods we offer. The data will be retrieved in the requested language. |
1 day | |
| GET | 3/lookup/importconfigupdatetypes |
Retrieve the list of import config update types |
1 day | |
| GET | 3/lookup/mediatypes |
Retrieve the list of media types. |
1 day | |
| GET | 3/lookup/metadatatypes |
Retrieve the list of metadata types |
1 day | |
| GET | 3/lookup/operators |
Retrieve the list of operators |
1 day | |
| GET | 3/lookup/optoutsources | 1 day | ||
| GET | 3/lookup/os |
Retrieve the os id and os name for all operating systems which we identify when completing a survey. (only in English) |
1 day | |
| GET | 3/lookup/questiontypes |
Retrieve the question type id and name for the question types. The data will be retrieved in the requested language. |
1 day | |
| GET | 3/lookup/queuestatus |
Lookup process queue status. |
1 day | |
| GET | 3/lookup/respondentstatus |
Retrieve respondent end status id and name for the respondent statuses. (only in English) |
1 day | |
| GET | 3/lookup/resultcodes |
Retrieve the list of ResultCodes which are returned when importing contacts or adding responses. |
1 day | |
| GET | 3/lookup/scaletypes |
Retrieve the scale type id and name of all possible scaletypes. |
1 day | |
| GET | 3/lookup/states |
Retrieve the ISO 3166-2 two-last letter state codes and name for all US states. (only in English) |
1 day | |
| GET | 3/lookup/surveylanguages |
Retrieve the list of languages which are support in the survey interface and can be used to when translating your survey. |
1 day | |
| GET | 3/lookup/surveystatus |
Retrieve the survey status id and name for all possible survey statuses. The data will be retrieved in the requested language. |
1 day | |
With the request you can retrieve all information regarding the media library
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
| GET | 3/media/{mediaid} |
Retrieve a media item by id. |
||
| GET | 3/media/folders |
Retrieve the complete tree of media folders. |
||
| GET | 3/media/folders/{folderid} |
Retrieve all media items from a media folder. |
||
| POST | 3/media/folders/{folderid} |
Add a new file to the media library. |
||
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
Occurs when a Panelist doesn't want to receive survey invitations anymore.
Required Roles
Contacts (read)
|
||||
| POST | webhooks/event/panelist/bounced |
Occurs when an email to a Panelist bounced. |
Contacts (read) |
|
| POST | webhooks/event/panelist/optout |
Occurs when a Panelist doesn't want to receive survey invitations anymore. |
Contacts (read) |
|
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
Occurs when a respondent completes a survey.
Required Roles
Results (read)
|
||||
|
Occurs for each page a respondent completes.
Required Roles
Results (read)
|
||||
|
Occurs when a respondent did not meet the criteria to respond and was directed to the alternative thank you page.
Required Roles
Results (read)
|
||||
| POST | webhooks/event/respondent/complete |
Occurs when a respondent completes a survey. |
Results (read) |
|
| POST | webhooks/event/respondent/pagesubmitted |
Occurs for each page a respondent completes. |
Results (read) |
|
| POST | webhooks/event/respondent/screenedout |
Occurs when a respondent did not meet the criteria to respond and was directed to the alternative thank you page. |
Results (read) |
|
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
| POST | webhooks/event/survey/created |
Occurs when a new survey is created. |
||
With the request you can retrieve all information regarding surveys: details about surveys, panelists, questions and respondents.
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
|
||||
|
Required Roles
Survey (write)
|
||||
|
|
||||
|
Required Roles
Survey (write)
|
||||
|
Required Roles
Survey (write)
|
||||
|
Retrieve all contacts from a survey which match the passed criteria. |
||||
|
Create a new contact in a survey.
Required Roles
Contacts (write)
|
||||
|
Retrieve the amount of unique values for the custom fields for a survey. |
||||
|
POST - 3/surveys/{surveyid}/launch
Required Roles
Survey (write)
|
||||
|
Required Roles
Survey (write)
|
||||
|
Required Roles
Survey (write)
|
||||
|
Required Roles
Survey (write)
|
||||
|
Retrieve all questions from a survey which match the passed criteria. |
||||
|
Required Roles
Survey (write)
|
||||
|
Retrieve a question from a survey by its datalabel. |
||||
|
Required Roles
Survey (write)
|
||||
|
Retrieve the aggregates (Average, Median, StandardDeviation, NPS) from a question by the question label.
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
|
||||
|
Retrieve the reults in aggregate for a question by id or datalabel. Hint: If you're looking to get the individual answers to a survey, download the respondents.
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
Retrieve all respondents from a survey which match the passed criteria. Use the
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
Add responses for a new respondent
Required Roles
Results (write)
|
||||
|
Get the respondent with responses from a survey.
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
Remove a respondent from a survey. This action is permanent and cannot be undone.
Required Roles
Results (write)
|
||||
| GET | 3/surveys |
Retrieve all surveys which match the passed criteria. |
1 minute | |
| POST | 3/surveys |
Create a new survey. |
Survey (write) |
|
| GET | 3/surveys/{surveyid} |
Retrieve a survey by id. |
||
| GET | 3/surveys/{surveyid}/channels/targetedpanels/urls |
|
||
| POST | 3/surveys/{surveyid}/channels/targetedpanels/urls |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/channels/targetedpanels/urls/{urlid} |
|
||
| PUT | 3/surveys/{surveyid}/channels/targetedpanels/urls/{urlid} |
|
Survey (write) |
|
| DELETE | 3/surveys/{surveyid}/channels/targetedpanels/urls/{urlid} |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/contacts |
Retrieve all contacts from a survey which match the passed criteria. |
||
| POST | 3/surveys/{surveyid}/contacts |
Create a new contact in a survey. |
Contacts (write) |
|
| GET | 3/surveys/{surveyid}/contacts/{contactid} |
Retrieve a contact from a survey by contactId. |
||
| PUT | 3/surveys/{surveyid}/contacts/{contactid} |
Update contact within a survey |
||
| GET | 3/surveys/{surveyid}/contacts/fieldvaluecount |
Retrieve the amount of unique values for the custom fields for a survey. |
||
| POST | 3/surveys/{surveyid}/launch |
|
Survey (write) |
|
| POST | 3/surveys/{surveyid}/pages/{pagenumber}/branching |
|
Survey (write) |
|
| PUT | 3/surveys/{surveyid}/pages/{pagenumber}/branching |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/pages/{pagenumber}/branching |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/questions |
Retrieve all questions from a survey which match the passed criteria. |
||
| POST | 3/surveys/{surveyid}/questions |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/questions/{questionid} |
Retrieve a question from a survey by its datalabel. |
||
| PUT | 3/surveys/{surveyid}/questions/{questionid} |
|
Survey (write) |
|
| GET | 3/surveys/{surveyid}/questions/{questionid}/aggregates |
Retrieve the aggregates (Average, Median, StandardDeviation, NPS) from a question by the question label. |
Results (read) |
1 minute |
| GET | 3/surveys/{surveyid}/questions/{questionid}/read |
|
||
| GET | 3/surveys/{surveyid}/questions/{questionid}/result |
Retrieve the reults in aggregate for a question by id or datalabel. Hint: If you're looking to get the individual answers to a survey, download the respondents. |
Results (read) |
1 minute |
| GET | 3/surveys/{surveyid}/respondents |
Retrieve all respondents from a survey which match the passed criteria. Use the |
Results (read) |
1 minute |
| POST | 3/surveys/{surveyid}/respondents |
Add responses for a new respondent |
Results (write) |
|
| GET | 3/surveys/{surveyid}/respondents/{respondentid} |
Get the respondent with responses from a survey. |
Results (read) |
1 minute |
| DELETE | 3/surveys/{surveyid}/respondents/{respondentid} |
Remove a respondent from a survey. This action is permanent and cannot be undone. |
Results (write) |
|
| GET | 3/surveys/{surveyid}/responserate |
Gets the response rate for a survey. |
||
Text analysis API: with these requests you can retrieve the results of your text analysis work
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
|
Retrieve the open answers
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
Retrieve the tagging aggregates
Required Roles
Results (read)
Cached Time
1 minute
|
||||
|
Retrieve a list of available tags for this question |
||||
| GET | 3/textanalysis/{surveyid}/questions |
Retrieve the open answer questions |
||
| GET | 3/textanalysis/{surveyid}/questions/{questionid} |
Retrieve the open answers |
Results (read) |
1 minute |
| GET | 3/textanalysis/{surveyid}/questions/{questionid}/aggregates |
Retrieve the tagging aggregates |
Results (read) |
1 minute |
| GET | 3/textanalysis/{surveyid}/questions/{questionid}/tags |
Retrieve a list of available tags for this question |
||
| Verb | Url | Description | Required Roles | Cached Time |
|---|---|---|---|---|
| POST | webhooks/event/webhook/created |
Occurs once a new webhook has been created. |
||