Surveymonkey Build Status Gem Version

This is a client for the SurveyMonkey RESTful API.


Add this line to your application's Gemfile:

gem 'surveymonkey'

And then execute:

$ bundle

Or install it yourself as:

$ gem install surveymonkey



The SurveyMonkey API is built on Mashery and works like other Mashery APIs. To access it, you'll need an API key and an access token; you'll be prompted to create these when you create a SurveyMonkey developer account.

Your API key is bound to a particular "application"; once you're logged into the SurveyMonkey developer site, you can create applications.

Access tokens are created via OAuth; you can either create one-off access tokens via the SurveyMonkey API console, or you can implement an OAuth flow of your own; there's more documentation here.

This gem requires that you specify both the API key and the access token at runtime. The access token can be changed between each API call; the API key is set once and then cannot be changed. Both of these can be read from environment variables, e.g.


API Methods

The SurveyMonkey API methods are documented here, under "API Methods". They are implemented as class methods, which you call like so:

[1] pry(main)> Surveymonkey.get_user_details
=> {"status"=>0,
    {"username"=>"XXXXXX", "is_paid_account"=>true, "is_enterprise_user"=>false}}}

To pass parameters to an API method, pass a hash like so:

[2] pry(main)> Surveymonkey.get_survey_list("page_size" => 5, "order_asc" => true)
=> {"status"=>0,

API method responses are parsed into Ruby data structures; do with them as you think best.

SurveyMonkey API responses include a status attribute. The possible values of this attribute are documented upstream; Surveymonkey::Client inspects each API response and raises a Surveymonkey::Error if the status code is other than 0.


After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

To Do

  • implement support for API v3
  • validate API method parameters client-side rather than server-side
  • more unit tests
  • better exception handling


  1. Fork it ( )
  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

Esteemed Contributors

  • @KazuyaMuroi
  • @cescue