Webinions.com API - latest API documentation

While we wanted to make Webinions.com very simple to get started with - we also wanted to make sure Webinions.com is ready to scale when you need more. The below API (Application Programming Interface) documentation defines the different options you have with Webinions.com.

You can use the API documentation to dynamically create the HTML that is needed to invoke Webinions.com Net Promoter Score survey. For subscribing customers there are also few advanced fetures that make Webinions.com the most powerful NPS service around.

Latest API version: 1.0

When integrating with Webinions Net Promoter Score survey, you need to include two html tags in your web page. The first tag is a DIV element with id "webinions-nps": <div id="webinions-nps" data-version="1.0"></div>. In addition to the identifier and API version, you can control what information is saved along the user's vote. You can also control how the survey is displayed on your web page. The below document explains which additional DATA attributes you can include in the DIV element.

The DIV element is followed by a SCRIPT element <script src="http://webinions.com/api/1.0/nps.js">.

Feature	Mandatory	Potential values	Default	Description
data-version	Yes	1.0	1.0	The version attribute is used to make sure we are able to change and add new functionalities the API without breaking the service for existing customers. The latest version (and only accepted value) is 1.0.
data-apikey	Yes	Char(20) - Your 20 character unique apikey		The API key is generated when you add your website to Webinions.com. This API key needs to be incldued in the survey so that we are able to attribute the user votes to your website. Don't worry - the API key cannot be used by other websites, since we do additional validation before the responses are saved.
data-country	No	Char(2) - Two character ISO 3166-1 country code	US	The two character country code is saved with each response. This provides you with regional segmentation of the incoming feedback. The default value (if not specified) is "US" which stands for "United States".
data-language	No	Char(2) - Two character ISO 639-1 language code	en	This can be used to try to open the survey in a specific language. We currently support only English surveys - but as time goes by we will add other languages to the service. If the requested langauge is not available, the survey will be shown in English. This two character language code is saved with each response. This provides you with language segmentation of the incoming feedback. The default value (if not specified) is "en" which stands for "English".
data-product	No	Varchar(50)	"this"	You can customize what the product / service the survey is asking feedback for. If this is not specified - the word "this" will be used in stead. e.g. "How likely are you to recommend this to a friend?"
data-mode	Yes	(modal | inline)	modal	This defineds how the survey will be shown on the web page. modal Modal dialog will be overlaid on top of any content on the page. If you choose "modal" you can include the Webinions html code anywhere in the web page inside the body tags. Please refer to our demo for an example of modal dialog survey. inline Inline will show the dialog exactly where the survey code is included.
data-importance	Yes	(mandatory | desired | optional)	desired	Applies for modal dialog only. Will be ignored for inline survey. mandatory User is not given an option to close the dialog by any other means than by answering the survey. desired User can close the dialog without answering, but the close button is not highly prominent. optional User can close the dialog without answring it - the close button is clearly visible to the user.
data-position	Yes	(left | center | right)	center	Applies for modal dialog only. Will be ignored for inline survey. left Dialog will be placed 100 pixels from top of the window and 10 pixels from the left. center Dialog will be placed 100 pixels from the top of the window and equally close to both sides of the browser. right Dialog will be placed 100 pixels from top of the window and 10 pixels from the right.
data-interval	Yes	Integer	100	The interval in days how often the survey is shown to user. The interval is saved locally on user's computer - so if user uses the service on multiple computers s/he may be shown the survey more often than the interval parameter defines. Feel free to implement additional logic on the server if you need to limit the visibility of the survey based on visits - or other criteria. Choosing the value as zero (0) will surface the survey every time the page is loaded by the user. Default value is 100 (days).
data-segment	No	Varchar(50)		A feature available for subscribers only. You can include a custom user segment to be saved with every vote. This property can be used to provide additional information about the user (e.g. "Purchaser", "Non-purchaser", "First time user"). There will be available reporting based on the custom segmentation.
data-user	No	Varchar(50)		A feature available for subscribers only. You can include a user identifier along with the vote. This can be used if you decide to pull the vote data into your own analytics system and you want to correlate the NPS votes with other behavior of the user. We recommend not to pass Personal Identifiable Information (PII) - but rather a system specific id or hash of some of user's PII (such as email).