This add-on is operated by Clearbit
Business intelligence APIs
Clearbit
Last updated January 30, 2017
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
Clearbit is an add-on for providing access to a set of businesses intelligence APIs for retrieving social data from emails, looking up company information from domains, and much more.
Clearbit’s Person API lets you look up an email address, returning information like a person’s name, avatar, location, Twitter handle and job information.
Likewise, Clearbit’s Company API lets you retrieve information about a company such as name, location, market categories, amount of funding raised, and headcount.
Clearbit is accessible via a REST API and has easy integration options for any language and framework. Examples have been included for Ruby and Node.js.
Provisioning the add-on
Clearbit can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
$ heroku addons:create clearbit
-----> Adding clearbit to sharp-mountain-4005... done, v18 (free)
Once Clearbit has been added a CLEARBIT_KEY
setting will be available in the app configuration and will contain the API key that can be used for authenticating with Clearbit. This can be confirmed using the heroku config:get
command.
$ heroku config:get CLEARBIT_KEY
After installing Clearbit the application should be configured to fully integrate with the add-on.
Local setup
Environment setup
After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.
Though less portable it’s also possible to set local environment variables using export CLEARBIT_KEY=value
.
Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env
file. To view all of your app’s config vars, type heroku config
. Use the following command to add the CLEARBIT_KEY values retrieved from heroku config to your .env
file.
$ heroku config -s | grep CLEARBIT_KEY >> .env
$ more .env
Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore
.
For more information, see the Heroku Local article.
Using with Ruby
Ruby applications will need to add the following entry into their Gemfile specifying the clearbit RubyGem.
gem 'clearbit'
Update application dependencies with bundler.
$ bundle install
Then from within your application you can look up an email address by:
Clearbit::Streaming::Person[email: 'test@example.com']
The example above is using our streaming API, and can block for up to 60 seconds. If this is an issue, i.e. you’re performing a look up inside a request/response cycle, we suggest you use our webhook API.
Looking up companies is similar, for example:
Clearbit::Streaming::Company[domain: 'uber.com']
Using with Node.js
Node.js applications will need to use the clearbit NPM package.
$ npm install clearbit
Then from within your application you can look up an email address by:
var clearbit = require('clearbit')(process.env.CLEARBIT_KEY);
clearbit.Person.find({email: 'test@example.com', stream: true})
.then(function (person) {
console.log('Name: ', person.name.fullName);
})
.catch(Person.NotFoundError, function (err) {
// Person could not be found
console.log(err);
})
.catch(function (err) {
// Clearbit Error
console.error(err);
});
Looking up companies is similar, for example:
var clearbit = require('clearbit')(process.env.CLEARBIT_KEY);
clearbit.Company.find({domain: 'uber.com', stream: true})
.then(function (company) {
console.log('Name: ', company.name);
})
.catch(Company.NotFoundError, function (err) {
// Company could not be found
console.log(err);
})
.catch(function (err) {
console.error(err);
});
Dashboard
For more information on the features available within the Clearbit dashboard please see the docs at clearbit.co/docs.
The Clearbit dashboard allows you to see your current and historical usage.
The dashboard can be accessed via the CLI:
$ heroku addons:open clearbit
Opening clearbit for sharp-mountain-4005…
or by visiting the Heroku Dashboard and selecting the application in question. Select Clearbit from the Add-ons menu.
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
Use the heroku addons:upgrade
command to migrate to a new plan.
$ heroku addons:upgrade clearbit:medium
-----> Upgrading clearbit:medium to sharp-mountain-4005... done, v18 ($49/mo)
Your plan has been updated to: clearbit:medium
Removing the add-on
Clearbit can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy clearbit
-----> Removing clearbit from sharp-mountain-4005... done, v20 (free)
Support
All Clearbit support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@clearbit.co.