Clearbit Ruby library
Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

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: 'alex@alexmaccaw.com', 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. If a person or company can't be found, then they'll 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.

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