clearbit-node

Node library for querying the Clearbit business intelligence APIs. Currently supports:

• Enrichment API
• Discovery API
• Watchlist API

Maintenance Status

This repository is currently not actively 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

Setup

$ npm install clearbit

var clearbit = require('clearbit')('api_key');
// or
var Client   = require('clearbit').Client;
var clearbit = new Client({key: 'api_key'});

Performing Lookups

Person

Person.find(options) -> Promise

• email String: The email address to look up (required)
• webhook_id String: Custom identifier for the webhook request
• subscribe Boolean: Set to true to subscribe to the changes
• stream Boolean: Set to true to use the streaming API instead of webhooks
• timeout Integer: The timeout in milliseconds after which a socket closed error will be thrown.

var Person = clearbit.Person;
Person.find({email: 'email@domain.com'})
  .then(function (person) {
    console.log('Name: ', person.name.fullName);
  })
  .catch(Person.QueuedError, function (err) {
    console.log(err); // Person is queued
  })
  .catch(Person.NotFoundError, function (err) {
    console.log(err); // Person could not be found
  })
  .catch(function (err) {
    console.log('Bad/invalid request, unauthorized, Clearbit error, or failed request');
  });

Company

Company.find(options) -> Promise

• domain String: The company domain to look up (required)
• webhook_id String: Custom identifier for the webhook request
• stream Boolean: Set to true to use the streaming API instead of webhooks
• timeout Integer: The timeout in milliseconds after which a socket closed error will be thrown.

var Company = clearbit.Company;
Company.find({domain: 'www.uber.com'})
  .then(function (company) {
    console.log('Name: ', company.name);
  })
  .catch(Company.QueuedError, function (err) {
    console.log(err); // Company is queued
  })
  .catch(Company.NotFoundError, function (err) {
    console.log(err); // Company could not be found
  })
  .catch(function (err) {
    console.log('Bad/invalid request, unauthorized, Clearbit error, or failed request');
  });

NameToDomain

NameToDomain.find(options) -> Promise

• name String: The company name to look up (required)
• timeout Integer: The timeout in milliseconds after which a socket closed error will be thrown.

var NameToDomain = clearbit.NameToDomain;
NameToDomain.find({name: 'Uber'})
  .then(function (result) {
    console.log('Domain: ', result.domain);
  })
  .catch(NameToDomain.NotFoundError, function (err) {
    console.log(err); // Domain could not be found
  })
  .catch(function (err) {
    console.log('Bad/invalid request, unauthorized, Clearbit error, or failed request');
  });

Prospector

Prospector.search(options) -> Promise

• domain String: The domain to search for. (required)
• role String: Employment role to filter by.
• roles Array[String]: Employment roles to filter by.
• seniority String: Employment seniority to filter by.
• seniorities Array[String]: Employment seniorities to filter by.
• title String: Job title to filter by.
• titles Array[String]: Job titles to filter by.
• city String: City to filter by.
• cities Array[String]: Cities to filter by.
• state String: State to filter by.
• states Array[String]: States to filter by.
• country String: Country to filter by.
• countries Array[String]: Countries to filter by.
• name String: Name of an individual to filter by.
• page Integer: The page of results to fetch.
• page_size Integer: The number of results per page.
• suppression String: Set to eu to exclude records with country data in the EU. Set to eu_strict to exclude records with country data in the EU or with null country data.

var Prospector = clearbit.Prospector;
Prospector.search({domain: 'clearbit.com'})
  .then(function (result) {
    console.log('Results: ', result.results);
  })
  .catch(function (err) {
    console.log('Bad/invalid request, unauthorized, Clearbit error, or failed request');
  });

Error Handling

Lookups return Bluebird promises. Any status code >=400 will trigger an error, including lookups than do not return a result. You can easily filter out unknown records from true errors using Bluebird's error class matching:

Person.find({email: 'notfound@example.com'})
  .catch(Person.NotFoundError, function () {
    // handle an unknown record
  })
  .catch(function () {
    // handle other errors
  });

Callbacks

If you really want to use node-style callbacks, use Bluebird's nodeify method:

Person.find({email: 'email@domain.com'}).nodeify(function (err, person) {
  if (err) {
    // handle
  }
  else {
    // person
  }
});