Impermium ruby client API wrapper
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead of weheartit:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Ruby wrapper for the Impermium API.

  • gem version 1.0.0 supports the Impermium API version 3.1
  • gem version 1.1.0 supports the Impermium API version 3.1 (upgraded hashie and yajl-ruby gems)
  • gem version 1.2.0 supports the Impermium API version 3.1 (upgraded dependency on faraday_middleware gem)


In order to use Impermium gem you must get an Impermium API key.

Instantiate and configure a client

The Impermium client can be instantiated and configured in several ways. A new client can be created with:

client = => <your_api_key>)

which is actually short for

client = => <your_api_key>)

Constructor accepts a hash of options that can be used to configure the Impermium client. Valid hash keys are:

  • :adapter (sets Faraday adapter)
  • :api_version (sets Impermium API version - default 3.1)
  • :api_key (sets API key)
  • :client_name (sets client name)
  • :client_id (sets client ID)
  • :endpoint (sets URL to Impermium server - default

Any of these values can be set directly too:

Finally, the Impermium client can be configured through a block with:

Impermium.configure do |conf|
  conf.api_key = <your_api_key>
  conf.endpoint = ""

client =

Calling API methods

Each method accepts the mandatory arguments of the corresponding API call, and takes an options hash and a block as optional arguments. Here is the list of all supported methods and their mandatory arguments:

  • USER

    • Account:

      • client.account(user_id, enduser_ip)
      • client.account_attempt(enduser_ip)
      • client.account_login(user_id, enduser_ip)
      • client.account_analyst_feedback(analyst_id, user_id, desired_result)
      • client.account_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, user_id, desired_result)
    • Profile:

      • client.profile(user_id, profile_id, enduser_ip)
      • client.profile_analyst_feedback(profile_id, analyst_id, desired_result)
      • client.profile_user_feedback(profile_id, rep_usr_id, rep_usr_type, reporter_ip, desired_result)

    • Blog post:

      • client.blog_post(user_id, blog_post_id, content, blog_post_permalink, blog_url, enduser_ip)
      • client.blog_post_analyst_feedback(analyst_id, blog_post_id, desired_result)
      • client.blog_post_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, blog_post_id, desired_result)
    • Bookmark:

      • client.bookmark(user_id, bookmark_id, bookmark_url, enduser_ip)
      • client.bookmark_like(user_id, bookmark_id, bookmark_url, like_value, enduser_ip)
      • client.bookmark_analyst_feedback(analyst_id, bookmark_id, desired_result)
      • client.bookmark_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, bookmark_id, desired_result)
    • Comment:

      • client.comment(user_id, comment_id, content, comment_permalink, article_permalink, enduser_ip)
      • client.comment_analyst_feedback(analyst_id, comment_id, desired_result)
      • client.comment_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, comment_id, desired_result)
    • Connection:

      • client.connection(operation, connection_type, connection_id, requester_user_id, responder_user_id, enduser_ip)
      • client.connection_analyst_feedback(analyst_id, connection_type, connection_id, desired_result)
      • client.connection_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, connection_type, connection_id, desired_result)
    • Listing:

      • client.listing(user_id, listing_id, content, listing_permalink, enduser_ip)
      • client.listing_analyst_feedback(analyst_id, listing_id, desired_result)
      • client.listing_user_feedback(rep_usr_id, rep_usr_type, reporter_ip, listing_id, desired_result)

Additional arguments can be passed through the hash which is the last argument for every method

client.account('33', '', {:alias => "user33", :password_hash=>'7d222a5d269a'})

If request headers have to be set it can be done through a block:

Impermium.account('33', '') do |req|
  req.headers = {:http_user_agent => "Impermium gem 1.0.0"}

You can find the complete arguments lists and types in the official Impermium API docs site.


Any method call receiving a successful response from impermium API will return a Hash-like structure containing the body of the response, typically including response_id, timestamp and possibly spam_classifier and any other additional classifiers.

Any 4XX response will raise an Impermium Exception with the body of the response in the error message.

  • A 400 status response from the impermium API will raise an Impermium::BadRequest
  • A 401 status response from the impermium API will raise an Impermium::UnauthorizedRequest
  • A 403 status response from the impermium API will raise an Impermium::ForbiddenRequest
  • A 404 status response from the impermium API will raise an Impermium::NotFoundRequest


Here is the list of contributors.


Copyright 2012 WHI Inc. (, released under the MIT license.