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

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