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
A Ruby API client to https://clearbit.com.
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: 'alex@alexmaccaw.com', stream: true)
person = result.person
company = result.companyPassing 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')
if result.pending?
# Lookup queued - try again later
end
# Later
unless result.pending?
person = result.person
company = result.company
endIn either case, if a person or company can't be found, the result will be nil.
See the documentation for more information.
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.
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.
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.
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 recommended
company_domain: 'clearbit.com', # 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: '89.102.33.1' # Optional, but strongly recommended when identifying users
} # as they sign up, or log in
)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 recommended
properties: {
url: 'https://github.com/clearbit/clearbit-ruby?utm_source=google', # 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: '89.102.33.1', # Optional, but strongly recommended.
},
)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
begin
webhook = Clearbit::Webhook.new(request.env)
webhook.type #=> 'person'
webhook.body.name.given_name #=> 'Alex'
# ...
rescue Clearbit::Errors::InvalidWebhookSignature => e
# ...
end
endThe global Clearbit.key can be overriden for multi-tenant apps using multiple Clearbit keys like so:
webhook = Clearbit::Webhook.new(request.env, 'CLEARBIT_KEY')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'
)