Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A Ruby API client to

Maintenance Status

This repository is currently not actively maintained. If you're looking to integrate with Clearbit's API we recommend looking at the HTTP requests available in our documentation at


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

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: '', # 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:password@proxyserver.tld:8080'