⚠️ DEPRECATION WARNING

This package is no longer being maintained. If you're looking to integrate with Clearbit's API we recommend looking at the HTTP requests available in our documentation at clearbit.com/docs

Clearbit

A Ruby API client to https://clearbit.com.

Installation

Add this line to your application's Gemfile:

gem 'clearbit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install clearbit

Usage

First authorize requests by setting the API key found on your account's settings page.

Clearbit.key = ENV['CLEARBIT_KEY']

Then you can lookup people by email address:

result = Clearbit::Enrichment.find(email: '[email protected]', stream: true)

person  = result.person
company = result.company

Passing the stream option makes the operation blocking - it could hang for 4-5 seconds if we haven't seen the email before. Alternatively you can use our webhook API.

Without the stream option, the operation is non-blocking, and we will immediately return either the enriched data or Clearbit::Pending object.

result = Clearbit::Enrichment.find(email: '[email protected]')

if result.pending?
  # Lookup queued - try again later
end

# Later
unless result.pending?
  person  = result.person
  company = result.company
end

In either case, if a person or company can't be found, the result will be nil.

See the documentation for more information.

Name to Domain

To find the domain based on the name of a resource, you can use the NameDomain API.

name = Clearbit::NameDomain.find(name: 'Uber')

For more information look at the documentation.

Company lookup

You can lookup company data by domain name:

company = Clearbit::Enrichment::Company.find(domain: 'uber.com', stream: true)

If the company can't be found, then nil will be returned.

See the documentation for more information.

Analytics

NOTE: We strongly recommend using clearbit.js for Analytics and integrating with Clearbit X. It handles a lot of complexity, like generating anonymous_ids and associating them with user_ids when a user is identified. It also automatically tracks page views with the full data set.

Identifying Users

Identify users by sending their user_id, and adding details like their email and company_domain to create People and Companies inside of Clearbit X.

Clearbit::Analytics.identify(
  user_id: '1234', # Required if no anonymous_id is sent. The user's ID in your database.
  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
  traits: {
    email: '[email protected]', # Optional, but strongly recommended
    company_domain: 'clearbit.com',     # Optional, but strongly recommended
    first_name: 'David', # Optional
    last_name: 'Lumley', # Optional
    # … other analytical traits can also be sent, like the plan a user is on etc
  },
  context: {
    ip: '89.102.33.1' # Optional, but strongly recommended when identifying users
  }                   # as they sign up, or log in
)

Page Views

Use the page method, and send the users anonymous_id along with the url they're viewing, and the ip the request comes from in order to create Companies inside of Clearbit X and track their page views.

Clearbit::Analytics.page(
  user_id: '1234', # Required if no anonymous_id is sent. The user's ID in your database.
  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
  name: 'Clearbit Ruby Library', # Optional, but strongly recommended
  properties: {
    url: 'https://github.com/clearbit/clearbit-ruby?utm_source=google', # Required. Likely to be request.referer
    path: '/clearbit/clearbit-ruby', # Optional, but strongly recommended
    search: '?utm_source=google', # Optional, but strongly recommended
    referrer: nil, # Optional. Unlikely to be request.referrer.
  },
  context: {
    ip: '89.102.33.1', # Optional, but strongly recommended.
  },
)

Other APIs

For more info on our other APIs (such as the Watchlist or Discover APIs), please see our main documentation.

Webhooks

For rack apps use the Clearbit::Webhook module to wrap deserialization and verify the webhook is from trusted party:

post '/v1/webhooks/clearbit' do
  begin
    webhook = Clearbit::Webhook.new(request.env)
    webhook.type #=> 'person'
    webhook.body.name.given_name #=> 'Alex'

    # ...
  rescue Clearbit::Errors::InvalidWebhookSignature => e
    # ...
  end
end

The global Clearbit.key can be overriden for multi-tenant apps using multiple Clearbit keys like so:

webhook = Clearbit::Webhook.new(request.env, 'CLEARBIT_KEY')

Proxy Support

Passing the proxy option allows you to specify a proxy server to pass the request through.

company = Clearbit::Enrichment::Company.find(
  domain: 'uber.com',
  proxy: 'https://user:[email protected]:8080'
)