⚠️ 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: 'alex@alexmaccaw.com',stream: true)person=result.personcompany=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: 'alex@alexmaccaw.com')ifresult.pending?# Lookup queued - try again laterend# Laterunlessresult.pending?person=result.personcompany=result.companyend

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: 'david@clearbitexample.com',# Optional, but strongly recommendedcompany_domain: 'clearbit.com',# Optional, but strongly recommendedfirst_name: 'David',# Optionallast_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 recommendedproperties: {url: 'https://github.com/clearbit/clearbit-ruby?utm_source=google',# Required. Likely to be request.refererpath: '/clearbit/clearbit-ruby',# Optional, but strongly recommendedsearch: '?utm_source=google',# Optional, but strongly recommendedreferrer: 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'dobeginwebhook=Clearbit::Webhook.new(request.env)webhook.type#=> 'person'webhook.body.name.given_name#=> 'Alex'# ...rescueClearbit::Errors::InvalidWebhookSignature=>e# ...endend

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