Full API V3 Reference

1. v3

• ApiRequest

  
  

  Verb	Url	Description	Required Roles	Cached Time
  POST - webhooks/event/apirequest/throttlinglimitreached 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

  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)
  POST - 3/contactfolders Create a new contacts folder. Required Roles Contacts (write)
  GET - 3/contactfolders/{id} Retrieve a contact folder by id. 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)

• ContactGroups

  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
  POST - 3/contactgroups Create a new contactgroup. Required Roles Contacts (write)
  GET - 3/contactgroups/{groupid} Retrieve a contact group by id. Required Roles Contacts (read)
  PUT - 3/contactgroups/{groupid} 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)
  GET - 3/contactgroups/{groupid}/contacts Retrieve all contacts from a contact group which match the passed criteria. Required Roles Contacts (read)
  POST - 3/contactgroups/{groupid}/contacts 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)
  PUT - 3/contactgroups/{groupid}/contacts/{contactid} Add an existing contact to a contact group. Required Roles 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. 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		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)

• Contacts

  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
  POST - 3/contacts Required Roles Contacts (write)
  POST - 3/contacts Required Roles Contacts (write)
  GET - 3/contacts/{contactid} Retrieve a contact by id. Required Roles Contacts (read)
  PUT - 3/contacts/{contactid} Update a contact by id. Required Roles Contacts (write)
  DELETE - 3/contacts/{contactid} Remove a contact by id. Required Roles 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. Required Roles Contacts (write)
  GET - 3/contacts/import/{queueitemid} Get the result of an import.
  POST - 3/contacts/import/configs Create a new import configuration. Required Roles Contacts (write)
  GET - 3/contacts/import/configs Retrieve the existing import configurations.
  PUT - 3/contacts/import/configs/{importconfigid} Update an existing import configuration. Required Roles Contacts (write)
  PUT - 3/contacts/import/configs/{importconfigid} Renames the import configuration. Required Roles Contacts (write)
  DELETE - 3/contacts/import/configs/{importconfigid} Remove a import configuration by id. Required Roles 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. Cached Time 1 day
  POST - 3/contacts/optouts Add new opt-outs for your account Required Roles Contacts (write)
  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		Contacts (write)
  POST	3/contacts		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)

• DefaultApi

  
  

  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.

• Hooks

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

• Keys

  
  

  Verb	Url	Description	Required Roles	Cached Time
  GET - 3/keys/current Get the roles related to the current key.
  GET	3/keys/current	Get the roles related to the current key.

• Lookup

  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
  GET - 3/lookup/importconfigupdatetypes Retrieve the list of import config update types Cached Time 1 day
  GET - 3/lookup/mediatypes Retrieve the list of media types. Cached Time 1 day
  GET - 3/lookup/optoutsources 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
  GET - 3/lookup/queuestatus Lookup process queue status. Cached Time 1 day
  GET - 3/lookup/respondentstatus 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/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

• Media

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

• Panelist

  
  

  Verb	Url	Description	Required Roles	Cached Time
  POST - webhooks/event/panelist/bounced Occurs when an email to a Panelist bounced. Required Roles Contacts (read)
  POST - webhooks/event/panelist/optout 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)

• Respondent

  
  

  Verb	Url	Description	Required Roles	Cached Time
  POST - webhooks/event/respondent/complete Occurs when a respondent completes a survey. Required Roles Results (read)
  POST - webhooks/event/respondent/pagesubmitted Occurs for each page a respondent completes. Required Roles 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. 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)

• Survey

  
  

  Verb	Url	Description	Required Roles	Cached Time
  POST - webhooks/event/survey/created Occurs when a new survey is created.
  POST	webhooks/event/survey/created	Occurs when a new survey is created.

• Surveys

  With the request you can retrieve all information regarding surveys: details about surveys, panelists, questions and respondents.

  
  

  Verb	Url	Description	Required Roles	Cached Time
  GET - 3/surveys Retrieve all surveys which match the passed criteria. Cached Time 1 minute
  POST - 3/surveys Create a new trial survey. Upgrading the survey to a paid survey can be done in our Tool.
  GET - 3/surveys/{surveyid} Retrieve a survey by id.
  GET - 3/surveys/{surveyid}/contacts Retrieve all contacts from a survey which match the passed criteria.
  POST - 3/surveys/{surveyid}/contacts Required Roles 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.
  GET - 3/surveys/{surveyid}/questions Retrieve all questions from a survey which match the passed criteria.
  GET - 3/surveys/{surveyid}/questions/{questionid} Retrieve a question from a survey by its datalabel.
  GET - 3/surveys/{surveyid}/questions/{questionid}/aggregates Retrieve the aggregates (Average, Median, StandardDeviation, NPS) from a question by the question label. Required Roles Results (read) Cached Time 1 minute
  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. Required Roles Results (read) Cached Time 1 minute
  GET - 3/surveys/{surveyid}/respondents Retrieve all respondents from a survey which match the passed criteria. Use the expand=Responses parameter to immediately include the responses of a respondent. Required Roles Results (read) Cached Time 1 minute
  POST - 3/surveys/{surveyid}/respondents Add responses for a new respondent Required Roles Results (write)
  GET - 3/surveys/{surveyid}/respondents/{respondentid} Get the respondent with responses from a survey. Required Roles Results (read) Cached Time 1 minute
  DELETE - 3/surveys/{surveyid}/respondents/{respondentid} Remove a respondent from a survey. This action is permanent and cannot be undone. Required Roles Results (write)
  GET - 3/surveys/{surveyid}/responserate Gets the response rate for a survey.
  GET	3/surveys	Retrieve all surveys which match the passed criteria.		1 minute
  POST	3/surveys	Create a new trial survey. Upgrading the survey to a paid survey can be done in our Tool.
  GET	3/surveys/{surveyid}	Retrieve a survey by id.
  GET	3/surveys/{surveyid}/contacts	Retrieve all contacts from a survey which match the passed criteria.
  POST	3/surveys/{surveyid}/contacts		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.
  GET	3/surveys/{surveyid}/questions	Retrieve all questions from a survey which match the passed criteria.
  GET	3/surveys/{surveyid}/questions/{questionid}	Retrieve a question from a survey by its datalabel.
  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}/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 expand=Responses parameter to immediately include the responses of a respondent.	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.

• TextAnalysis

  Text analysis API: with these requests you can retrieve the results of your text analysis work

  
  

  Verb	Url	Description	Required Roles	Cached Time
  GET - 3/textanalysis/{surveyid}/questions Retrieve the open answer questions
  GET - 3/textanalysis/{surveyid}/questions/{questionid} Retrieve the open answers Required Roles Results (read) Cached Time 1 minute
  GET - 3/textanalysis/{surveyid}/questions/{questionid}/aggregates Retrieve the tagging aggregates Required Roles Results (read) Cached Time 1 minute
  GET - 3/textanalysis/{surveyid}/questions/{questionid}/tags 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

• Webhook

  
  

  Verb	Url	Description	Required Roles	Cached Time
  POST - webhooks/event/webhook/created Occurs once a new webhook has been created.
  POST	webhooks/event/webhook/created	Occurs once a new webhook has been created.