A Ruby API client to


Add this line to your application's Gemfile:

gem 'clearbit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install clearbit


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 =

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

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

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: '', stream: true)

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

See the documentation for more information.


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.

  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: '',     # 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: '' # 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.
  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: '', # 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: '', # 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.


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

post '/v1/webhooks/clearbit' do
    webhook =
    webhook.type #=> 'person' #=> 'Alex'

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

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

webhook =, '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: '',
  proxy: 'https://user:[email protected]:8080'