API Docs

JavaScript API

Initialize SatisfactionHub via JavaScript
You can find your site's script under Site Settings, after logging in.
Example: Initialize SatisfactionHub Using JavaScript
    action: "purchase confirmation",
    user: "123456789",
    email: "johnDoe@mydomain.com",
    created_at: 1369259742
Example: Initialize SatisfactionHub Using JavaScript and Schedule an Email Survey
In this example, an email survey will be scheduled for July 1, 2013, 10:00AM PST. You can also call SatisfactionHub.show() to display an overlay widget immediately. The email will still be sent.
    action: "homepage",
    user: "123456789",
    email: "usersemail@domain.com",
    email_datetime: 1372698000
Example: Initialize SatisfactionHub Using a DOM Element (id="satisfactionhub")
Use a span or other element with id="satisfactionhub" and html5 data attributes specifying your options. If SatisfactionHub is configured to display an inline widget, it will be added to your page at this element's location.
<span id="satisfactionhub" data-user="123456789" data-email="johnDoe@mydomain.com" data-action="purchase confirmation"></span>
Initialization Options
SatisfactionHub can be initialized via the JavaScript SatisfactionHub.init() method or by including an "#satisfactionhub" element with HTML5 data attributes for configuration. Pass your options as an object of key/value pairs to SatisfactionHub.init() or use data-{option_name}="option_value" accordingly.
Option Name Type Default Required description
user string no A unique identifier to identify your site visitor. This allows you to track responses of individual users. We recommend using a user id, email address, or username.
email string no An email address for your site visitor. This allows you to send email surveys from SatisfactionHub and see a user's email address and gravatar in the SatisfactionHub reports dashboard.
created_at timestamp (seconds) no This field allows you to specify a created, or sign-up time, for the visitor. This is used to trigger surveys based on time since sign-up. If you don't specify this, we'll automatically calculate it based on when we first see a visitor.
email_datetime timestamp (seconds) no Specify this to schedule an feedback survey to be emailed to the visitor at the specified date/time in seconds. Set this to "now" to send immediately. Only one email may queued per visitor, and we automatically make sure visitors don't get more than one of these emails per month.
Note: for an email to be scheduled you must also pass in a user and email as separate attributes.
user_type string no A type of user to your site. This can be used to easily segment users. For example, if your site has a Free and Pro version, you could use data-user_type="free" and data-user_type="pro" to measure satisfaction scores for these different groups.
action string no An identifier for the workflow action or page your visitor is on. If you don't pass this in, we'll automatically generate this from the current url fragment. This can be used to compare satisfaction scores across multiple pages and features as well as conduct A/B tests. For example, you could use data-action="shopping cart" and data-action="order complete" to measure satisfaction scores for users while on a shopping cart screen versus those who completed an order.
callback function no The initialized site ID will be returned to the callback function when initialization is complete.
JavaScript Methods

If you add the SatisfactionHub element to your DOM after page load, you can call SatisfactionHub.init() to force the script to re-initialize itself. Optionally, you can pass configuration options as an object of key/value pairs. If you are using data- attributes to specify configuration options, do not pass options into SatisfactionHub.init() as your data- attributes will be ignored.


Pass a string into this method to trigger actions after initializing SatisfactionHub.


Displays the SatisfactionHub widget in an overlay. Note that the widget will not be displayed to a visitor if they have already responded within the configured survey repeat interval (set through SatisfactionHub.com).


Closes the widget overlay, if shown.


Our comprehensive REST api offers access to all resources in the context of a site API Token.

View our documentation on apiary.io

Web Hooks

REST Hooks are available to subscribe to specific events, such as new survey responses. See our REST API documentation for more info.

View our documentation on apiary.io