Skip to content
Impermium ruby client API wrapper
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.

Something went wrong with that request. Please try again.