Gem for accessing the api
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


promoter is a wrapper for the REST API.

You can find the API docs here:


First off you need to grab your api key.

Add this line to your application's Gemfile:

gem 'promoter'

And then execute:

$ bundle

Or install it yourself as:

$ gem install promoter

Set your api key with:

Promoter.api_key = 'YOUR API KEY'

(Put this into an initializer i.e. app/initializers/promoter.rb if using Rails.)


Get all feedback

Promoter::Feedback.all(score: 8) # => returns all feedback with a score of 8
# this is paginated. Pass page: 2 to get the second page
# (I know, this is different from the other api calls! This will be fixed in later versions)

Possible filters: score Filter by the score score_type Filters by the score type: promoter, detractor, passive survey_campaign Filter by the campaign id survey_campaign_status Filter by the campaign status: ACTIVE, COMPLETE

Get a specific feedback

Promoter::Feedback.find(79) #=> id of the feedback to return


Get all contacts

Promoter::Contact.all(page: 2) # => this is paginated - returns page 2 of results

To find the a contact by an email pass in the email option:

Promoter::Contact.all(email: "")

Get a specific contact


Create a contact

Promoter::Contact.create(email: "",    # required
                         first_name: "Chris",           # optional
                         last_name: "O'Sullivan",       # optional
                         contact_list: [599],           # array of contact list ids to add to
                         campaign: 78,                  # campaign which this belongs to
                         attributes: { plan: 'silver' } # any extra data you want to add to the contact
                         send: false )                  # set this to true to send the NPS immediately

Remove a contact


Survey a contact

Promoter::Contact.survey(email: "",    # required
                         first_name: "Chris",           # optional
                         last_name: "O'Sullivan",       # optional
                         campaign: 78,                  # campaign which this belongs to
                         attributes: { plan: 'silver' })# any extra data you want to add to the contact


Create a campaign

Promoter::Campaign.create(name: "Campaign Name",    # required
                          contact_list: 1,          # required
                          email: 1)                 # required

Get all campaigns

Promoter::Campaign.all(page: 2) # => this is paginated - returns page 2 of results

Send surveys for a campaign

Promoter::Campaign.send_surveys(33, false)

This takes two parameters, the campaign id, and a boolean as to send out surveys to ALL of the customers for the campaign. (This is defaulted to false!)

Contact lists

Create a contact list

Promoter::ContactList.create(name: "List Name")    # required

Get all contact lists

Promoter::ContactList.all(2)  # => this is paginated - returns page 2 of results

Get All Contacts for a Contact List

# => returns an array of contact ids for a contact list id

Remove a contact from a contact list

Promoter::ContactList.remove_contact(contact_list_id: 7899,
                                     contact_id: 15777)

Remove a contact from a contact list by email

Promoter::ContactList.remove_contact(contact_list_id: 7899,
                                     email: "")

Remove a contact from all contact lists

Promoter::ContactList.remove_contact(contact_email: "")

Email Templates

Create an email template

Promoter::EmailTemplate.create(name: "Campaign Name", # required
               subject: "Email Name",                 # required
               logo: "<base64EncodedImageData>",      # required
               reply_to_email: "",           # required
               from_name: "Name",                     # required
               intro_message: "Message",              # required
               language: "en",                        # required
               company_brand_product_name: "name")    # required

Get all email templates

Promoter::EmailTemplate.all # => returns all results


# => returns a list of interesting metrics that promoter has for your account


  1. Fork it ([my-github-username]/promoter/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request