API Reference

Install the Ruby bindings using the clearbit gem.

# Use rubygems
gem install clearbit

# Or use bundler
gem 'clearbit'

Then require the gem.

require 'clearbit'

Install the Node bindings using the clearbit npm package.

npm install clearbit

Then require the package.

var clearbit = require('clearbit');

Install the Python bindings using the clearbit package.

# Use PyPI
pip install clearbit

# Or use easy_install
easy_install clearbit

Then import the package.

import clearbit

Welcome to Clearbit’s API! You can use this API to access all our API endpoints, such as the Person API to look up email addresses, or the Company API to look up company information related to a domain name.

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

We also have some specific language bindings to make integration easier. You can switch the programming language of the examples with the tabs in the top right.

Currently we support the following official client bindings:

To play around with a few examples, we recommend a REST client called Postman. Simply tap the button below to import a pre-made collection of examples.

Authentication

Authentication using HTTP basic auth.

curl 'https://person.clearbit.com/v1/people/email/alex@alexmaccaw.com' \
        -u {key}:

require 'clearbit'

Clearbit.key = '{key}'

var clearbit = require('clearbit')('{key}');

import clearbit

clearbit.key = '{key}'

Alternatively pass a Bearer token in an Authorization header.

curl 'https://person.clearbit.com/v1/people/email/alex@alexmaccaw.com' \
        -H 'Authorization: Bearer {key}'

Authentication is done via the API key which you can find in your account settings.

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Alternatively you can also pass your API key as a bearer token in an Authorization header.

You can see your account’s API keys, and roll them if necessary, in the dashboard.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

HTTP Status codes

Code	Title	Description
200	OK	The request was successful.
201	Created	The resource was successfully created.
202	Async created	The resource was asynchronously created
400	Bad request	Bad request
401	Unauthorized	Your API key is invalid.
402	Over quota	Over plan quota on this endpoint.
404	Not found	The resource does not exist.
422	Validation error	A validation error occurred.
50X	Internal Server Error	An error occurred with our API.

Error types

All errors are returned in the form of JSON with a type and optional message.

Example error response.

  {
    "error": {
      "type": "params_invalid",
      "message": "Name is required"
    }
  }

Type	Description
params_invalid	Your parameters were not valid.
unknown_record	Record was not found.
unknown_route	URL was not valid.
queued	Lookup queued. Try this request again in a few minutes.
rate_limit	The request has been rate limited.
api_error	Internal API error.

Rate limiting

Check to see how many requests we have left:

$ curl -i https://person.clearbit.com

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2014 21:20:00 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4050
X-RateLimit-Reset: 3300

You can make 600 requests per minute to each API, unless you are using Streaming. Check the returned HTTP headers of any API request to see your current rate limit status. If you’re running into this error or think you’ll need a higher rate limit, drop us a line at support@clearbit.com. The Streaming version of each API is limited to 5 concurrent connections rather than being limited by the number of requests per minute.

Example rate limit error response.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1402010983
Retry-After: 50

Content-Type: application/json
  {
    "error": {
      "type": "rate_limit",
      "message": "Rate limit exceeded. Limit is 600 requests per minute. Rate limit will be reset in 50 seconds."
    }
  }

Header	Name
`X-RateLimit-Limit`	The maximum number of requests that the consumer is permitted to make per minute.
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.
`X-RateLimit-Reset`	The time at which the current rate limit window resets in UTC epoch seconds.
`Retry-After`	The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.

Once you go over the rate limit you will receive a rate_limit error response.

Versioning

You can pass a specific API version like so:

curl 'https://person.clearbit.com/v1/people/email/alex@clearbit.com' \
        -H 'API-Version: 2016-08-31' \
        -u {key}:

Clearbit::Person.version = '2016-08-31'

var clearbit = require('clearbit')('{key}');
clearbit.Person.setVersion('2016-08-31');

import clearbit

clearbit.Person.version = '2016-08-31'

When we make backwards-incompatible changes to any of our APIs, we release new dated versions. Each API we provide has a separate version (listed below).

All requests will use your account API settings, unless you override the API version by sending a API-Version header identifying the API version to use. (For libraries and bindings, this is done by setting an API version property as in the code examples.)

Any webhooks triggered will also use a request specified version before falling back to your account’s version.

You can visit your dashboard to upgrade your API version. You can also see a full API version changelog here.

API	Current Version
Person API	2016-08-31
Company API	2017-01-02
Watchlist API	2015-11-13

Webhooks

The incoming webhook POST request’s body is formatted as JSON, and looks like this:

{
  "id": "custom_id",
  "status": 200,
  "body": {
    "name": {
      "givenName": "Alex",
      "familyName": "MacCaw",
      "fullName": "Alex MacCaw"
    },
    "//": "..."
  }
}

Here’s how you’d process a webhook request in Rails.

# webhook_controller.rb
class WebhookController < ApplicationController
  def clearbit
    webhook = Clearbit::Webhook.new(env)

    case webhook.type
    when 'person'
      person = Person.find(webhook.id)
      person.clearbit = webhook.body
      person.unknown  = webhook.status == 404
      person.save
    end

    head 200
  end
end

# routes.rb
post 'webhook/clearbit' => 'webhook#clearbit'

And here’s how you’d process a webhook request in Sinatra.

post '/v1/webhooks/clearbit' do
  webhook = Clearbit::Webhook.new(env)

  case webhook.type
  when 'person'
    person = Person[webhook.id]
    person.clearbit = webhook.body
    person.unknown  = webhook.status == 404
    person.save
  end

  200
end

Certain requests, such as looking up an email address, may have an asynchronous response (since there’s some complex background processing involved). For these requests you can either poll the endpoint, or give us a webhook URL you want to be called when the request has finished processing.

You can set a webhook URL endpoint in your account settings to be used with all requests. Alternatively, you can pass along a webhook_url query parameter along with requests.

To link up your requests to webhooks you can pass a webhook_id parameter when making these calls, containing a custom defined webhook identifier. We’ll pass this identifier back to you with the webhook request.

If you return anything other than a HTTP 200 status to the webhook POST then we’ll try to deliver the webhook up to 5 times with an exponential backoff.

Response POST body

Attribute	Description
`id`	string Custom user-supplied webhook identifier.
`type`	string Either `person`, `company`, `person_company`, or `candidate_match`.
`status`	integer Either a `200` status code (record was found), or a `404` status code (record was not found).
`body`	hash Result object, either `null` or the encoded person.

For testing webhooks, we recommend a useful service called requestb.in, which allows you to inspect arbitrary webhook requests.

Securing webhooks

To validate a webhook came from Clearbit we suggest verifying the webhook payloads with the X-Request-Signature header (which we pass with every webhook). If you’re using one of our client bindings to parse webhooks, say the Ruby library, we’ll do this for you.

Header	Name
`X-Request-Signature`	A SHA1 HMAC hexdigest computed with your API key and the raw body of the request. Make sure to strip the prefix (`sk_`, `pk_`) from the start of the key before generating the HMAC.

Streaming

To look up a person:

result = Clearbit::Enrichment.find(email: 'alex@alexmaccaw.com', stream: true)

if person = result.person
  puts "Name: #{person.name.full_name}"
end

curl 'https://person-stream.clearbit.com/v1/people/email/alex@alexmaccaw.com' \
        -u {key}:

var clearbit = require('clearbit')('{key}');

clearbit.Person.find({email: 'alex@clearbit.com', stream: true})
  .then(function (person) {
    console.log('Name: ', person.name.fullName);
  });

person = clearbit.Person.find(email='alex@alexmaccaw.com', stream=True)
if person != None:
  print "Name: " + person['name']['fullName']

Or to look up a company:

company = Clearbit::Company.find(domain: 'stripe.com', stream: true)

if company
  puts "Name: #{company.name}"
end

curl 'https://company-stream.clearbit.com/v1/companies/domain/stripe.com' \
        -u {key}:

var clearbit = require('clearbit')('{key}');

clearbit.Company.find({domain: 'stripe.com', stream: true})
  .then(function (company) {
    console.log('Name: ', company.name);
  });

company = clearbit.Company.find(domain='stripe.com', stream=True)
if company != None:
  print "Name: " + company['name']

An alternative to using webhooks is our streaming API. This API is ideal if you don’t mind long lived requests (e.g. you’re making requests to Clearbit from a messaging queue).

When we need to do an asynchronous lookup, say when looking up a person by email address, rather than requiring you to poll the endpoint the streaming API will simply keep the connection open until we have some data.

Requests made to the streaming API will never return a HTTP 202 status response, and can be held open for up to a minute.

The only difference between making calls to the normal and streaming API is the subdomain - person-stream.clearbit.com rather than person.clearbit.com.

OAuth

For you Ruby coders, we have a drop-in pre-written OmniAuth integration.

You can build apps on top of Clearbit’s platform and provide seamless authentication using our OAuth 2 endpoint. To get started, first request client credentials from us.

The relevent endpoints are listed below:

Create a request token

To create an OAuth request token, send your users to the endpoint below passing in the required query parameters. After authorization, users will be redirected back to your application. From there you access your newly generated request token as the code query parameter.

GET https://clearbit.com/oauth/authorize

Query params

Parameter	Description
`client_id`	string (required) Your application’s client ID
`redirect_uri`	string (required) URL to redirect users back to

Create an access token

A response to generate an access token looks like this:

{
  "access_token": "sk_123"
}

Once a user has been through the OAuth flow and been redirected back to your application, you can create an access token which you can use for future authentication.

POST https://clearbit.com/oauth/access_token

Query params

Parameter	Description
`client_id`	string (required) Your application’s client ID
`client_secret`	string (required) Your application’s client secret
`code`	string (required) Your request token generated in the last step

Enrichment API

The Enrichment API lets you look up person and company data based on an email or domain. For example, you could retrieve a person’s name, location and social handles from an email. Or you could lookup a company’s location, headcount or logo based on their domain name.

Note: You’ll only be charged once per 30 day period for each unique request, so if you didn’t store the data properly or need to re-run a series of requests for any reason, those won’t count against your allotment.

Combined API

To lookup both a company and person based on an email address:

curl 'https://person-stream.clearbit.com/v2/combined/find?email=alex@alexmaccaw.com' \
        -u {key}:

response = Clearbit::Enrichment.find(email: 'alex@alexmaccaw.com', stream: true)

if person = response.person
  puts person.name.fullName
end

if company = response.company
  puts company.name
end

var clearbit = require('clearbit')('{key}');

clearbit.Enrichment.find({email: 'alex@alexmaccaw.com', stream: true})
  .then(function (response) {
    var person  = response.person;
    var company = response.company;

    console.log('Name: ', person && person.name.fullName);
  })
  .catch(function (err) {
    console.error(err);
  });

response = clearbit.Enrichment.find(email='alex@alexmaccaw.com', stream=True)

if response['person'] is not None:
  print response['person']['name']['fullName']

if response['company'] is not None:
  print response['company']['name']

The stream option ensures that the request blocks until Clearbit has found some data on both the person & company. For cached information this will return in the region of 300 milliseconds, for uncached requests 2-4 seconds. If speed is key, you can omit the stream option and try the request again later (if you receive a pending response). Alternatively you can use our webhook API.

curl 'https://person.clearbit.com/v2/combined/find?email=alex@alexmaccaw.com' \
        -u {key}:

response = Clearbit::Enrichment.find(email: 'alex@alexmaccaw.com')

if response.pending?
  # Lookup queued - try again later
end

if person = response.person
  puts person.name.fullName
end

if company = response.company
  puts company.name
end

var clearbit = require('clearbit')('{key}');

clearbit.Enrichment.find({email: 'alex@alexmaccaw.com'})
  .then(function (response) {
    var person  = response.person;
    var company = response.company;

    console.log('Name: ', person && person.name.fullName);
  })
  .catch(clearbit.Enrichment.QueuedError, function (err) {
    // Lookup is queued
    console.log(err);
  })
  .catch(function (err) {
    console.error(err);
  });

response = clearbit.Enrichment.find(email='alex@alexmaccaw.com')

if 'pending' in response:
  # Lookup queued - try again later

if 'person' in response:
  print response['person']['name']['fullName']

if 'company' in response:
  print response['company']['name']

A common use-case is looking up a person and company simultaneously based on a email address. To save you making two requests to do this, we offer a combined lookup API.

This endpoint expects an email address, and will return an object containing both the person and company (if found). A call to the combined lookup will only count as one API call.

The API response object looks like the following. Note that either the ‘person’ or ‘company’ attribute can be nil if not found. For a full look at the attributes returned, see either the Person or Company attribute sections.

{
  "person": {
    "id": "d54c54ad-40be-4305-8a34-0ab44710b90d",
    "name": {
      "fullName": "Alex MacCaw",
      "givenName": "Alex",
      "familyName": "MacCaw"
    },
    "email": "alex@alexmaccaw.com",
    "//": "..."
  },
  "company": {
    "id": "c5a6a9c5-303a-455a-935c-9dffcd2ed756",
    "name": "Alex MacCaw",
    "legalName": "Alex MacCaw",
    "domain": "alexmaccaw.com",
    "//": "..."
  }
}

HTTP Request

GET https://person.clearbit.com/v2/combined/find?email=:email

(Where :email is the person’s email address)

HTTP GET params

Alongside the email address you may also provide any additional attributes you have about the person, such as their given and family names. Including more detail will help us be more accurate when searching.

The supported parameters are:

param	Description
email	string (required) The email address to look up.
webhook_url	string A webhook URL that results will be sent to.
given_name	string First name of person.
family_name	string Last name of person. If you have this, passing this is strongly recommended to improve match rates.
ip_address	string IP address of the person. If you have this, passing this is strongly recommended to improve match rates.
location	string The city or country where the person resides.
company	string The name of the person’s employer.
company_domain	string The domain for the person’s employer.
linkedin	string The LinkedIn URL for the person.
twitter	string The Twitter handle for the person.
facebook	string The Facebook URL for the person.
webhook_id	string Custom identifier for the webhook request.
subscribe	boolean Set to `true` to subscribe to the changes to the person.

Response Types

Code	Description
200	Successful lookup, person & company encoded in the response body.
202	Asynchronously looking up the person & company.
404	Neither the Person or the Company were found.

Person API

The Person API lets you retrieve social information associated with an email address, such as a person’s name, location and Twitter handle.

Attributes

The dot notation indicates that the property is one level deep inside a hash. No attributes are guaranteed to be present, and if we can’t find data on a specific network, then we’ll return a null value for that attribute.

The JSON encoded response looks like this.

{
  "id": "d54c54ad-40be-4305-8a34-0ab44710b90d",
  "name": {
    "fullName": "Alex MacCaw",
    "givenName": "Alex",
    "familyName": "MacCaw"
  },
  "email": "alex@alexmaccaw.com",
  "gender": "male",
  "location": "San Francisco, CA, US",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -8,
  "geo": {
    "city": "San Francisco",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "lat": 37.7749295,
    "lng": -122.4194155
  },
  "bio": "O'Reilly author, software engineer & traveller. Founder of https://clearbit.com",
  "site": "http://alexmaccaw.com",
  "avatar": "https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/d54c54ad-40be-4305-8a34-0ab44710b90d",
  "employment": {
    "domain": "clearbit.com",
    "name": "Clearbit",
    "title": "Founder and CEO",
    "role": "ceo",
    "seniority": "executive"
  },
  "facebook": {
    "handle": "amaccaw"
  },
  "github": {
    "handle": "maccman",
    "avatar": "https://avatars.githubusercontent.com/u/2142?v=2",
    "company": "Clearbit",
    "blog": "http://alexmaccaw.com",
    "followers": 2932,
    "following": 94
  },
  "twitter": {
    "handle": "maccaw",
    "id": "2006261",
    "bio": "O'Reilly author, software engineer & traveller. Founder of https://clearbit.com",
    "followers": 15248,
    "following": 1711,
    "location": "San Francisco",
    "site": "http://alexmaccaw.com",
    "avatar": "https://pbs.twimg.com/profile_images/1826201101/297606_10150904890650705_570400704_21211347_1883468370_n.jpeg"
  },
  "linkedin": {
    "handle": "pub/alex-maccaw/78/929/ab5"
  },
  "googleplus": {
    "handle": null
  },
  "aboutme": {
    "handle": "maccaw",
    "bio": "Software engineer & traveller. Walker, skier, reader, tennis player, breather, ginger beer drinker, scooterer & generally enjoying things :)",
    "avatar": "http://o.aolcdn.com/dims-global/dims/ABOUTME/5/803/408/80/http://d3mod6n032mdiz.cloudfront.net/thumb2/m/a/c/maccaw/maccaw-840x560.jpg"
  },
  "gravatar": {
    "handle": "maccman",
    "urls": [
      {
        "value": "http://alexmaccaw.com",
        "title": "Personal Website"
      }
    ],
    "avatar": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",
    "avatars": [
      {
        "url": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",
        "type": "thumbnail"
      }
    ]
  },
  "fuzzy": false,
  "emailProvider": false,
  "indexedAt": "2016-11-07T00:00:00.000Z"
}

Attribute	Description
`id`	string Internal ID
`name.givenName`	string First name of person (if found)
`name.familyName`	string Last name of person (if found)
`name.fullName`	string Full formatted name of person. Sometimes this will be present even if the givenName or familyName aren’t available
`gender`	string `male` or `female`
`location`	string The most accurate location we have
`timeZone`	string The timezone for the person’s location
`utcOffset`	integer The offset from UTC in hours in the person’s location
`geo.city`	string Normalized city based on location
`geo.state`	string Normalized state based on location
`geo.country`	string Normalized two letter country code based on location
`geo.lat`	float General latitude based on location
`geo.lng`	float General longitude based on location
`bio`	string The most accurate bio we have
`site`	string The person’s website
`avatar`	string The best avatar url we have
`employment.name`	string Company name
`employment.title`	string Title at Company
`employment.role`	string Role at Company
`employment.seniority`	string Seniority at Company
`employment.domain`	string Company domain
`facebook.handle`	string Facebook ID or screen name
`github.handle`	string GitHub handle
`github.id`	integer GitHub ID
`github.avatar`	string GitHub avatar
`github.company`	string GitHub company
`github.blog`	string GitHub blog url
`github.followers`	string Count of GitHub followers
`github.following`	string Count of GitHub following
`twitter.handle`	string Twitter screen name
`twitter.id`	integer Twitter ID
`twitter.followers`	integer Count of Twitter followers
`twitter.following`	integer Count of Twitter friends
`twitter.location`	string Twitter location
`twitter.site`	string Twitter site
`twitter.statuses`	integer Tweet count
`twitter.favorites`	integer Favorite count
`twitter.avatar`	string HTTP Twitter avatar
`linkedin.handle`	string LinkedIn url (i.e. /pub/alex-maccaw/78/929/ab5)
`googleplus.handle`	string Google Plus handle
`aboutme.handle`	string about.me handle
`aboutme.bio`	string about.me bio
`aboutme.avatar`	string about.me avatar URL
`gravatar.handle`	string Gravatar handle
`gravatar.urls`	array Array of URLs from Gravatar
`gravatar.avatar`	string Gravatar main avatar url.
`gravatar.avatars`	string Array of objects containing a avatar url, and a type (i.e. thumbnail)
`fuzzy`	boolean Indicating whether or not the lookup is a fuzzy or exact search
`emailProvider`	boolean is the email domain associated with a free email provider (i.e. Gmail)?
`indexedAt`	string date The time at which we indexed this data

Email lookup

The Person API allows you to look up a person by their email address. Alongside the email address you may also provide any additional attributes you have about the person, such as their given and family names. Including more detail will help us be more accurate when searching.

The supported parameters are:

param	Description
email	string (required) The email address to look up.
webhook_url	string A webhook URL that results will be sent to.
given_name	string First name of person.
family_name	string Last name of person. If you have this, passing this is strongly recommended to improve match rates.
ip_address	string IP address of the person. If you have this, passing this is strongly recommended to improve match rates.
location	string The city or country where the person resides.
company	string The name of the person’s employer.
company_domain	string The domain for the person’s employer.
linkedin	string The LinkedIn URL for the person.
twitter	string The Twitter handle for the person.
facebook	string The Facebook URL for the person.

To look up a person by email address, run the following. The call will either return nil (in which case a person wasn’t found), a blank object that responds to ‘pending?’, in which case the lookup is queued, or the relevant person object.

person = Clearbit::Enrichment::Person.find(email: 'alex@alexmaccaw.com', company: 'Clearbit')

if person && !person.pending?
  puts "Name: #{person.name.fullName}"
end

To look up a person by email address, run the following. The command will either return a 404 (in which case the person wasn’t found), a 202 indicating the lookup has been queued, or a JSON object containing the relevant person.

curl 'https://person.clearbit.com/v2/people/find?email=alex@alexmaccaw.com&company=Clearbit' \
        -u {key}:

To look up a person by email address, run the following. Note that if the call to pending() returns true the lookup is queued—you should the lookup again later or alternatively use our webhook API.

var clearbit = require('clearbit')('{key}');
var Person   = clearbit.person;

Person.find({email: 'alex@alexmaccaw.com', company: 'Clearbit'})
  .then(function (person) {
    console.log('Name: ', person.name.fullName);
  })
  .catch(Person.QueuedError, function (err) {
    // Lookup is queued - try again later
    console.log(err);
  })
  .catch(Person.NotFoundError, function (err) {
    // Person could not be found
    console.log(err);
  })
  .catch(function (err) {
    console.error(err);
  });

To look up a person by email address, run the following. The call will either return None (in which case a person wasn’t found), a dict { ‘pending’: true }, in which case the lookup is queued, or the relevant person dict.

person = clearbit.Person.find(email='alex@alexmaccaw.com', company='Clearbit')

if person != None and 'pending' not in person:
    print "Name: " + person['name']['fullName']

If you’d rather the request blocked until we find something (up to 60 seconds for uncached emails, but usually in the order of 10 seconds), then you can use our streaming API:

person = Clearbit::Person.find(email: 'alex@alexmaccaw.com', company: 'Clearbit', stream: true)

if person
  puts "Name: #{person.name.full_name}"
end

curl 'https://person-stream.clearbit.com/v2/people/find?email=alex@alexmaccaw.com' \
        -u {key}:

var clearbit = require('clearbit')('{key}');

clearbit.Person.find({email: 'stripe.com', company: 'Clearbit', stream: true})
  .then(function (person) {
    console.log('Name: ', person.name.fullName);
  });

person = clearbit.Person.find(email='alex@alexmaccaw.com', company='Clearbit', stream=True)
if person != None:
  print "Name: " + person['name']['fullName']

This endpoint retrieves a person by email address. If we can find the person we’ll return a 200 status containing the record’s attributes.

Sometimes we’ll need to asynchronously lookup the person, in which case we’ll return an empty 202 status. Either try the same request again in a few minutes to get the full response, or register a webhook to be notified when we’ve finished searching for an email.

If we can’t find any information associated with the email address, we’ll return a 404 status.

HTTP Request

GET https://person.clearbit.com/v2/people/find?email=:email

(Where :email is the person’s email address)

HTTP GET params

You can also pass the following optional parameters along when looking up people.

param	Description
webhook_id	string Custom identifier for the webhook request.
subscribe	boolean Set to `true` to subscribe to the changes.

Response Types

Code	Description
200	Successful lookup, person encoded in the response body.
202	Asynchronously looking up the person.
404	Person not found.

Subscribe to a person’s updates by passing the ‘subscribe’ parameter.

curl 'https://person.clearbit.com/v2/people/find?email=alex@alexmaccaw.com&subscribe=true' \
        -u {key}:

Clearbit::Enrichment::Person.find(email: 'alex@alexmaccaw.com', subscribe: true)

var clearbit = require('clearbit')('{key}');

clearbit.Person.find({email: 'alex@alexmaccaw.com', subscribe: true});

clearbit.Person.find(email='alex@alexmaccaw.com', subscribe=True)

You can subscribe to changes in people’s information by passing a subscribe parameter when looking up people. Whenever we receive updates, we’ll post them to the webhook url associated with your account. This will count as an API call.

You can set the webhook url associated with your account in your account’s settings.

Flagging

To flag a person’s data as incorrect

curl 'https://person.clearbit.com/v1/people/d54c54ad-40be-4305-8a34-0ab44710b90d/flag' \
        -XPOST \
        -d 'given_name=Alexander' \
        -d 'employment_title=The Great' \
        -u {key}:

person = Clearbit::Enrichment::Person.find(email: 'alex@alexmaccaw.com')
person.flag!(given_name: 'Alexander', employment_title: 'The Great')

var clearbit = require('clearbit')('{key}');

clearbit.Person.find({email: 'alex@alexmaccaw.com'})
  .then(function (person) {
    person.flag({
      givenName: 'Alexander',
      employmentTitle: 'The Great'
    });
  })

person = clearbit.Person.find(email='alex@alexmaccaw.com')
person.flag(given_name='Alexander', employment_title='The Great')

While we do our best to always return accurate data, we’re only ~~lizards~~ human and sometimes we make mistakes. This is especially true when the lookup is a fuzzy match rather than an exact one.

This endpoint allows you to let us know if a person doesn’t seem quite right. You can flag a person as incorrect and also optionally pass through a correct set of attributes.

We look into all the flagging we receive and incorporate fixes into future results.

HTTP Request

POST https://person.clearbit.com/v1/people/:id/flag

Where :id is the id of the person you’d like to flag as inaccurate.

HTTP POST params

You can also optionally pass to us corrected versions of any of the person’s attributes we sent you.

param	Description
`given_name`	string (optional) First name of person
`family_name`	string (optional) Last name of person
`employment_title`	string (optional) Company title
`facebook_handle`	string (optional) Facebook ID or screen name
`github_handle`	string (optional) GitHub handle
`twitter_handle`	string (optional) Twitter screen name
`linkedin_handle`	string (optional) LinkedIn url (i.e. /pub/alex-maccaw/78/929/ab5)
`googleplus_handle`	string (optional) Google Plus handle.
`aboutme_handle`	string (optional) about.me handle

Response types

Code	Description
200	Successful received, we will look into the issue.
404	Person not found.

Company API

Our Company API lets you lookup company data via a domain name.

Attributes

The JSON encoded response looks like:

{
  "id": "3f5d6a4e-c284-4f78-bfdf-7669b45af907",
  "name": "Uber",
  "legalName": "Uber Technologies, Inc.",
  "domain": "uber.com",
  "domainAliases": [
    "uber.org",
    "ubercab.com"
  ],
  "site": {
    "title": "Uber",
    "h1": "Your Ride, On Demand",
    "metaDescription": "Get a taxi, private car or rideshare from your mobile phone. Uber connects you with a driver in minutes. Use our app in cities around the world.",
    "metaAuthor": null,
    "phoneNumbers": [],
    "emailAddresses": [
      "domains@uber.com"
    ]
  },
  "category": {
    "sector": "Information Technology",
    "industryGroup": "Software & Services",
    "industry": "Internet Software & Services",
    "subIndustry": "Internet Software & Services"
  },
  "tags": [
    "Technology",
    "Marketplace",
    "Mobile",
    "B2C",
    "Ground Transportation",
    "Transportation",
    "Internet"
  ],
  "description": "Get a taxi, private car or rideshare from your mobile phone. Uber connects you with a driver in minutes. Use our app in cities around the world.",
  "foundedYear": 2009,
  "location": "1455 Market St, San Francisco, CA 94103, USA",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -7,
  "geo": {
    "streetNumber": "1455",
    "streetName": "Market Street",
    "subPremise": null,
    "city": "San Francisco",
    "postalCode": "94103",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "lat": 37.7752315,
    "lng": -122.4175278
  },
  "logo": "https://logo.clearbit.com/uber.com",
  "facebook": {
    "handle": "uber"
  },
  "linkedin": {
    "handle": "company/uber-com"
  },
  "twitter": {
    "handle": "Uber",
    "id": "19103481",
    "bio": "Evolving the way the world moves by seamlessly connecting riders to drivers through our app. Question, concern, or praise? Tweet at @Uber_Support.",
    "followers": 570351,
    "following": 377,
    "location": "Global",
    "site": "http://t.co/11eIV5LX3Z",
    "avatar": "https://pbs.twimg.com/profile_images/697242369154940928/p9jxYqy5_normal.png"
  },
  "crunchbase": {
    "handle": "organization/uber"
  },
  "emailProvider": false,
  "type": "private",
  "ticker": null,
  "phone": null,
  "indexedAt": "2016-11-07T00:00:00.000Z",
  "metrics": {
    "alexaUsRank": 544,
    "alexaGlobalRank": 943,
    "employees": 20313,
    "employeesRange": "1000+",
    "marketCap": null,
    "raised": 10610000000,
    "annualRevenue": null
  },
  "tech": [
    "google_analytics",
    "double_click",
    "mixpanel",
    "optimizely",
    "typekit_by_adobe",
    "android",
    "nginx",
    "ios",
    "mixpanel",
    "google_apps"
  ]
}

A company object looks as follows. The dot notation indicates that the property is one level deep inside a hash. No attributes are guaranteed to be present, and if we can’t find data on a specific network (say Twitter), then we’ll return a null value for that attribute.

Attribute	Description
`id`	string Internal ID
`name`	string Name of company
`legalName`	string Legal name of company
`domain`	string Domain of company’s website
`domainAliases`	array List of domains also used by the company
`site.title`	string HTML title contents of company’s website
`site.phoneNumbers`	array List of phone numbers mentioned on the company’s website
`site.emailAddresses`	array List of email addresses mentioned on the company’s website
`tags`	array List of market categories (see a complete list)
`category.sector`	string Broad sector (see a complete list)
`category.industryGroup`	string Industry group (see a complete list)
`category.industry`	string Industry (see a complete list)
`category.subIndustry`	string Sub industry (see a complete list)
`description`	string Description of the company
`foundedYear`	integer Year company was founded
`location`	string Address of company
`timeZone`	string The timezone for the company’s location
`utcOffset`	integer The offset from UTC in hours in the company’s location
`geo.streetNumber`	string Headquarters street number
`geo.streetName`	string Headquarters street name
`geo.subPremise`	string Headquarters suite number
`geo.city`	string Headquarters city name
`geo.state`	string Headquarters state name
`geo.stateCode`	string Headquarters two character state code
`geo.postalCode`	string Headquarters postal/zip code
`geo.country`	string Headquarters country name
`geo.countryCode`	string Headquarters two character country code
`geo.lat`	float Headquarters latitude
`geo.lng`	float Headquarters longitude
`metrics.raised`	integer Total amount raised
`metrics.alexaUsRank`	integer Alexa’s US site rank
`metrics.alexaGlobalRank`	integer Alexa’s global site rank
`metrics.employees`	integer Amount of employees
`metrics.marketCap`	integer Market Cap
`metrics.annualRevenue`	integer Annual Revenue (public companies only)
`facebook.handle`	string Company’s Facebook ID
`linkedin.handle`	string Company’s Linkedin URL
`twitter.handle`	string Twitter screen name
`twitter.id`	integer Twitter ID
`twitter.bio`	string Twitter Bio
`twitter.followers`	integer Count of Twitter followers
`twitter.following`	integer Count of Twitter friends
`twitter.location`	string Twitter location
`twitter.site`	string Twitter site
`twitter.avatar`	string HTTP Twitter avatar
`crunchbase.handle`	string Crunchbase handle
`logo`	string SRC of company logo
`emailProvider`	boolean is the domain associated with a free email provider (i.e. Gmail)?
`type`	string The company’s type, either `education`, `government`, `nonprofit`, `private`, `public`, or `personal`.
`phone`	string International headquarters phone number
`tech`	array Array of technology tags
`indexedAt`	string date The time at which we indexed this data

Domain lookup

The Company API allows you to look up a company by their domain. Alongside the domain you may also provide any additional attributes you have about the company, such as their company name or twitter handle. Including more detail will help us be more accurate when searching.

The supported parameters are:

param	Description
domain	string (required) The domain to look up.
webhook_url	string A webhook URL that results will be sent to.
company_name	string The name of the company.
linkedin	string The LinkedIn URL for the company.
twitter	string The Twitter handle for the company.
facebook	string The Facebook URL for the company.

To look up a company by name name, run the following. The call will either return nil (in which case a company wasn’t found), a blank object that responds to ‘pending?’ in which case the lookup is queued, or the relevant company object.

company = Clearbit::Enrichment::Company.find(domain: 'stripe.com', company_name: 'Stripe, Inc.')

if company && !company.pending?
  puts "Name: #{company.name}"
end

To look up a company by domain name, run the following. The command will either return a 404 (in which case the company wasn’t found), a 422 if the domain name is invalid (doesn’t exist, or doesn’t resolve), a 202 indicating the lookup has been queued, or a 200 returning the relevant company.

curl 'https://company.clearbit.com/v2/companies/find?domain=stripe.com' \
        -u {key}:

To lookup a company by domain name, run the following.

var clearbit = require('clearbit')('{key}');

clearbit.Company.find({domain: 'uber.com'})
  .then(function (company) {
    console.log('Name: ', company.name);
  })
  .catch(Company.QueuedError, function (err) {
    // Company lookup queued - try again later
  })
  .catch(Company.NotFoundError, function (err) {
    // Company could not be found
    console.log(err);
  })
  .catch(function (err) {
    console.error(err);
  });

To lookup a company by domain name, run the following.

company = clearbit.Company.find(domain='stripe.com')
if company != None and 'pending' not in company:
  print "Name: " + company['name']

This endpoint retrieves a company by domain name. If we can find the company we’ll return a 200 status containing the record’s attributes.

Sometimes we’ll need to asynchronously lookup the company, in which case we’ll return an empty 202 status. Either try the same request again in a few minutes to get the full response, or register a webhook to be notified when we’ve finished searching for a company.

If we can’t find any information associated with the domain name, we’ll return a 404 status.

HTTP Request

GET https://company.clearbit.com/v2/companies/find?domain=:domain

Where :domain is the company’s domain name.

HTTP GET params

You can also pass the following optional parameters along when looking up companies.

param	Description
webhook_id	string Custom identifier for the webhook request.

Response types

Code	Description
200	Successful lookup, company encoded in the response body.
202	Asynchronously looking up the company.
404	Company not found.
422	Domain name is invalid.

Flagging

To flag a company’s data as incorrect

curl 'https://company.clearbit.com/v1/companies/3823d7e8-4710-4e6c-b4cf-4e7c151d1767/flag' \
        -XPOST \
        -d 'name=Stripe' \
        -u {key}:

company = Clearbit::Enrichment::Company.find(domain: 'stripe.com')
company.flag!(name: 'Stripe')

var clearbit = require('clearbit')('{key}');

clearbit.Company.find({domain: 'stripe.com'})
  .then(function (company) {
    company.flag({
      name: 'Stripe'
    });
  })

company = clearbit.Company.find(domain='stripe.com')
company.flag(name='Stripe')

While we do our best to always return accurate data sometimes we can make mistakes. The flagging endpoint allows you to let us know if a company doesn’t seem quite right. You can flag a company as incorrect and also optionally pass through a correct set of attributes.

We look into all the flagging we receive and incorporate fixes into future results.

HTTP Request

POST https://company.clearbit.com/v1/companies/:id/flag

Where :id is the id of the company you’d like to flag as inaccurate.

HTTP POST params

You can also optionally pass to us corrected versions of any of the company’s attributes we sent you.

param	Description
`name`	string (optional) Name of company
`tags`	array List of market categories the company is involved in
`description`	string Description of the company
`raised`	integer Total amount raised
`location`	string Address of company
`facebook_handle`	string (optional) Facebook ID or screen name
`twitter_handle`	string (optional) Twitter screen name
`linkedin_handle`	string (optional) LinkedIn URL (i.e. /pub/alex-maccaw/78/929/ab5)
`crunchbase_handle`	string Crunchbase handle
`employees`	integer Amount of employees
`logo`	string SRC of company logo
`email_provider`	boolean is the domain associated with a free email provider (i.e. Gmail)?
`type`	string Type of company (`education`, `government`, `nonprofit`, `private`, `public`, `personal`)

Response types

Code	Description
200	Successful received, we will look into the issue.
404	Company not found.

Discovery API

Our Discovery API lets you search for companies via specific criteria. For example, you could search for all companies with a specific funding, that use a certain technology, or that are similar to your existing customers.

The Discovery API is currently under limited release.
To get access to the API, please contact us.

Attributes

The JSON encoded response looks like this:

{
  "total": 605410,
  "page": 1,
  "results": [
    {
      "name": "Clearbit",
      "domain": "clearbit.com",
      "//": "..."
    }
  ]
}

Every search response includes the following three fields:

Name	Description
`total`	Total amount of companies matching the search
`page`	Page number for pagination
`results`	Array of company responses

Request

Our search API lets you filter by over 30 different attributes. For example, to find all companies using Marketo that have raised over 100k run:

Clearbit::Discovery.search(
  query: {tech: 'marketo', raised: '100000~'},
  sort: 'alexa_asc'
)

clearbit.Discovery.search(
  query={'tech': 'marketo', 'raised': '100000~'},
  sort='alexa_asc'
)

clearbit.Discovery.search({query: {tech: 'marketo', raised: '100000~'}})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=and:(tech:marketo raised:100000~)' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

We support over 30 different query parameters to help you filter results and find the companies you’re looking for.

Each company returned will count towards the monthly quota.

URL

GET https://discovery.clearbit.com/v1/companies/search

Response codes

Code	Description
200	Successful lookup, search response encoded in the response body.
422	Invalid search (request has a malformed query param).

Params

The query param is required to make search.

Param	Description
`query`	string Search query string.

You can also pass the following optional parameters along when searching for companies.

Param	Description
`page`	integer Which results page to show (default is `1`).
`page_size`	integer The amount of results to return per page.
`limit`	integer How many paginated results to return in total.
`sort`	string Which order results are returned in.

Pagination

To retrieve an additional page pass the page option:

Clearbit::Discovery.search(
  query: {twitter_followers: '10000~'},
  page: 2
)

clearbit.Discovery.search(
  query={'twitter_followers': '10000~'},
  page=2
)

clearbit.Discovery.search({query: {twitter_followers: '10000~'}, page: 2})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=twitter_followers:10000~' \
  --data-urlencode 'page=2' \
  -u {key}:

Search requests return a maximum of 10 results per page. You can paginate through results and receive the next set by incrementing the page param.

Sorting

To sort by a specific attribute using the sort option.

Clearbit::Discovery.search(
  query: {tech: 'marketo'},
  sort: 'google_rank'
)

clearbit.Discovery.search(
  query={'tech': 'marketo'},
  sort='google_rank'
)

clearbit.Discovery.search({query: {tech: 'marketo'}, sort: 'google_rank'})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:marketo' \
  --data-urlencode 'sort=google_rank' \
  -u {key}:

To sort in a particular direction append _asc or _desc to the sort option:

Clearbit::Discovery.search(
  query: {tech: 'marketo'},
  sort: 'alexa_asc'
)

clearbit.Discovery.search(
  query={'tech': 'marketo'},
  sort='alexa_asc'
)

clearbit.Discovery.search({query: {tech: 'marketo'}, sort: 'alexa_asc'})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:marketo' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

By default search results are sorted by the best match available. You can change this to a specific sort using the sort parameter and one of the values below.

You can toggle between ascending and descending sorts by appending _asc and _desc respectively.

Sort	Description
`score`	Default sort
`alexa_rank`	Alexa ranking
`employees`	Number of employees
`google_rank`	Google rank
`market_cap`	Market cap for public companies
`raised`	Amount of funding raised
`twitter_followers`	Number of Twitter followers

Queries

Queries are space separated key colon values. For example to find all companies with an Alexa rank between 1 & 1000, 30 employees or more, and based in SF the query would look like this:

  alexa_rank:0~1000 employees:30~ city:"San Francisco"

As you can see, you can escape values by using quotes. You can also include sub queries by using parenthesis:

  and:(tech:stripe raised:10000~)

Alternatively, rather than using a string search query, you can also pass an array of hashes:

Clearbit::Discovery.search(
  query: [{tech: 'marketo'}, {alexa_rank: '0~1000'}]
)

Alternatively, rather than using a string search query, you can also pass an array of dicts:

clearbit.Discovery.search(
  query=[{'tech': 'marketo'}, {'raised': '100000~'}]
)

Alternatively, rather than using a string search query, you can also pass an array of objects:

clearbit.Discovery.search({query: [{tech: 'marketo'}, {alexa_rank: '0~1000'}]})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

Queries to the Discovery API can be as complex or as simple as you need them to be. Queries are passed along as strings in the query parameter using the type:value format. Take a look at the examples on the right.

Data types

Every query option is one of the following data types:

type	Description
`string`	Letters
`integer`	Number
`range`	Range of numbers separated by a tilde (`~`). Omit the first or last integer to scan the full range.

Fields

The following fields are supported:

Param	Description
`domain`	string Exact domain match
`name`	string Fuzzy name match
`description`	string Fuzzy description match
`and`	query AND query (see below)
`or`	query OR query (see below)
`alexa_rank`	range Global Alexa rank
`alexa_us_rank`	string US Alexa rank
`google_rank`	range Google Page Rank
`location`	string Fuzzy long form address match
`state`	string Two letter state code
`city`	string Long form city name of headquarters
`country`	string Two letter country code of headquarters
`crunchbase`	string Crunchbase handle
`employees`	range Headcount
`facebook`	string Facebook handle
`linkedin`	string LinkedIn handle
`twitter`	string Twitter handle
`twitter_followers`	range Number of Twitter followers
`twitter_following`	range Number of Twitter friends
`market_cap`	range Market cap
`ticker`	string Stock ticker symbol
`raised`	range Amount of funding raised
`industry`	string Categorization industry
`sub_industry`	string Categorization sub-industry (see a complete list)
`sector`	string Categorization sector (see a complete list)
`tag`	string Categorization tags (see a complete list)
`similar`	string Domain name of similar company (see below)
`tech`	string Tech used (see below)
`type`	string Company type (education/government/nonprofit/private/public/personal)
`has`	string Only return companies who have data for the given field. Aliased as ‘exists’
`hasnt`	string Only return companies who don’t have data for the given field. Aliased as ‘missing’

AND/OR queries

By default queries use an AND search - results have to satisfy all parameters. To change this behavior use the or query type and pass a sub-query:

  or:(twitter_followers:10000~ type:nonprofit)

For example, to find all companies that have at least 10000 Twitter followers or are charities:

Clearbit::Discovery.search(
  query: {or: [{twitter_followers: '10000~'}, {type: 'nonprofit'}]}
)

clearbit.Discovery.search(
  query={'or': [{'twitter_followers': '10000~'}, {'type': 'nonprofit'}]}
)

clearbit.Discovery.search({query: {or: [{twitter_followers: '10000~'}, {type: 'nonprofit'}]}})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=or:(twitter_followers:10000~ type:nonprofit)' \
  -u {key}:

By default, queries are are filtered by an AND match. That is, if you provide multiple query options, results must match all of them of them. You can change this behavior to OR matching (where matches to all criteria are preferred, but not required) by using a OR query.

Similar queries

You can search for companies similar to other ones by domain:

  similar:stripe.com

For example, to find any companies similar to Salesforce:

Clearbit::Discovery.search(query: {similar: 'salesforce.com'})

clearbit.Discovery.search(query={'similar': 'salesforce.com'})

clearbit.Discovery.search({query: {similar: 'salesforce.com'}})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=similar:salesforce.com' \
  -u {key}:

To find ‘look-alike’ companies–companies that are similar to each other–you can use the similar query. Pass a company’s domain and we’ll try and find similar companies. This is particularly useful for taking your existing customer list and finding new leads.

Tech queries

To search for companies using particular front-end technologies use the tech query:

  tech:stripe tech:customer_io tech:segment

For example, to find any companies that use Google Apps sorted by Alexa score:

Clearbit::Discovery.search(
  query: {tech: 'google_apps'},
  sort: 'alexa_asc'
)

clearbit.Discovery.search(
  query={'tech': 'google_apps'},
  sort='alexa_asc'
)

clearbit.Discovery.search({query: {tech: 'google_apps'}}})
  .then(function (search) {
    console.log('Results:', search.results);
  })
  .catch(function (err) {
    console.error(err);
  });

curl 'https://discovery.clearbit.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:google_apps' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

Whenever we index a company’s website, we also detect any technologies they’re using such as their analytics provider, email provider, or payments provider. We then surface over 60 different technologies in our search API letting you filter by them.

You can find a full list of technologies we index here.

Prospector API

The Prospector API lets you fetch contacts and emails associated with a company, employment role, seniority, and job title.

The Prospector API is currently under limited release.
To get access to the API, please contact us.

Person search

To search for people by domain name, run the following.

people = Clearbit::Prospector.search(domain: 'twitter.com', role: 'marketing')

people.each do |person|
  puts [person.name.full_name, person.title].join(' - ')
end

var clearbit = require('clearbit')('{key}');

clearbit.Prospector.search({domain: 'twitter.com', role: 'marketing'})
  .then(function (people) {
    people.forEach(function(person){
      console.log(person.name.fullName, person.title);
    });
  })
  .catch(function (err) {
    console.error(err);
  });

people = clearbit.Prospector.search(domain='twitter.com', role='marketing')

for person in people:
  print person['name']['fullName']

curl 'https://prospector.clearbit.com/v1/people/search' \
        -G --data-urlencode 'domain=twitter.com' \
        --data-urlencode 'role=marketing' \
        -u {key}:

This endpoint returns an array of people who work at a specific company.

HTTP Request

GET https://prospector.clearbit.com/v1/people/search

HTTP GET params

You can also pass the following parameters along when searching for people.

param	Description
`domain`	string (required) Domain of the company you want to search against.
`role`	string (optional) Employment Role (view list).
`roles[]`	string (optional) Multiple roles to filter by. You can specify this param multiple times to search for multiple roles.
`seniority`	string (optional) Employment Seniority (view list).
`seniorities[]`	string (optional) Multiple seniorities to filter by. You can specify this param multiple times to search for multiple seniorities.
`title`	string (optional) Job title to filter by.
`titles[]`	string (optional) Multiple job titles to filter by. You can specify this param multiple times to search for multiple titles.
`name`	string (optional) Name of an individual to filter by.
`limit`	integer (optional) Limit the number of maximum results returned in the response (default is 5, max is 20).

Response Types

Code	Description
200	Successful lookup, person encoded in the response body.
406	Validation error

Response body

The JSON encoded response looks like this.

[
  {
    "id": "7416592A-A0D5-4AE5-ACB0-03156E444E9C",
    "name": {
      "givenName": "Harlow",
      "familyName": "Ward",
      "fullName": "Harlow Ward"
    },
    "title": "Co Founder at Clearbit",
    "role": "founder",
    "seniority": "executive",
    "email": "harlow@clearbit.com",
    "verified": true,
    "phone": "+1 415-555-1212"
  }
]

Attribute	Description
`id`	string Internal ID
`name.givenName`	string First name of person
`name.familyName`	string Last name of person
`name.fullName`	string Full formatted name of person
`title`	string Employment title
`role`	string Employment role (view list).
`seniority`	string Employment seniority (view list).
`email`	string Corporate Email Address
`verified`	boolean Do we have an exact match on email?
`phone`	string Premium Feature: Direct dial phone work number (requires additional plan)

Reveal API

Our Reveal API takes an IP address, and returns the company associated with that IP. This is especially useful for de-anonymizing traffic on your website, analytics, and customizing landing pages for specific company verticals.

Powering Reveal is a unique dataset that combines both public and proprietary sources to give you an insight into the companies visiting your website whatever their size, even if they don’t have their own public ASN block.

The Reveal API is currently under limited release.
To get access to the API, please contact us.

Lookup IP addresses

To use the Reveal API, send us an IP address and we’ll return the company domain and information associated. If we can’t match the IP to a company, we’ll return a 404 HTTP status instead of a 200.

Attributes

The JSON encoded response looks like this.

{
  "ip": "62.210.77.51",
  "fuzzy": true,
  "domain": "segment.com",
  "company": {
    "name": "Segment",
    "tags": [
      "Software",
      "SAAS",
      "B2B",
      "Information Technology & Services",
      "Technology",
      "Internet"
    ],
    "metrics": {
      "alexaUsRank": 23403,
      "alexaGlobalRank": 26266,
      "employees": 95,
      "employeesRange": "51-250",
      "raised": 44600000
    },
    "...":  "..."
  }
}

In the case above, ‘...’ represents a truncated company response. You can find the full company response under the Company Attributes section.

Attribute	Description
`ip`	string IP address that was looked up
`fuzzy`	boolean False if the company has their own dedicated ASN network, otherwise true.
`domain`	string The matched company domain
`company`	object A full company response

HTTP Request

To lookup an IP address, run the following:

curl 'https://reveal.clearbit.com/v1/companies/find?ip=62.210.77.51' \
        -u {key}:

Clearbit::Reveal.find(
  ip: '62.210.77.51'
)

result = clearbit.Reveal.find(
  ip='62.210.77.51'
)

print result

var clearbit = require('clearbit')('{key}');

clearbit.Reveal.find({
    ip: '62.210.77.51'
  })
  .then(function (result) {
    console.log('Result', result);
  })
  .catch(function (err) {
    console.error(err);
  });

GET https://reveal.clearbit.com/v1/companies/find

HTTP GET parameters

The following parameters are supported.

Parameter	Description
`ip`	string (required) IP address to lookup

Response types

Code	Description
200	Successful lookup
404	Company not found
422	Invalid parameters

Client-side endpoint

Sometimes you’ll want to look up an IP address directly from a users browser, say to customize the page based on the company viewing it. Our public Reveal endpoint returns data about the IP address that made the request, and can be authenticated with a publishable key.

GET https://reveal.clearbit.com/v1/companies/reveal

HTTP GET parameters

The following parameters are supported.

Parameter	Description
`authorization`	string (required) Your publishable key (starts with a `pk_`)
`callback`	string (optional) A JSONP callback function to be invoked
`variable`	string (optional) A JavaScript variable name to be set

Response types

Code	Description
200	Successful lookup (or a JSONP or JS var response)
404	Company not found

JSONP response

<script>
  function myCallback(response) {
    console.log(response && response.company);
  }
</script>
<script src="https://reveal.clearbit.com/v1/companies/reveal?authorization=pk_test&callback=myCallback"></script>

One of the simplest ways of using this API is via a JavaScript script tag using JSONP. Simply pass the name of the function you’d like to be invoked as the callback parameter.

This method of calling the API has the advantage of blocking page load, so is useful for customizing the page on the fly.

JavaScript variable response

<script src="https://reveal.clearbit.com/v1/companies/reveal?authorization=pk_test&variable=myVariable"></script>
<script>
  console.log(myVariable && myVariable.company)
</script>

Similarily to the JSONP method above, you can pass in the variable parameter when making a request, which will indicate you want the response to be set to a global JavaScript variable. Again, this makes sense when requesting the API from a script tag.

Autocomplete API

Company Autocomplete is a free API that lets you auto-complete company names and retreive logo and domain information.

Send requests with paritial company name to endpoint:

curl 'https://autocomplete.clearbit.com/v1/companies/suggest?query=stripe'

The JSON encoded response looks like this:

[
  {
    "domain": "stripe.com",
    "logo": "https://logo.clearbit.com/stripe.com",
    "name": "Stripe"
  },
  {
    "domain": "stripesgroup.com",
    "logo": "https://logo.clearbit.com/stripesgroup.com",
    "name": "Stripes Group"
  }
]

HTTP Request

GET https://autocomplete.clearbit.com/v1/companies/suggest?query=:name

Where :name is the partial name of the company.

HTTP Response

Responses will include the following three fields:

Name	Description
`domain`	Domain name of company
`logo`	URL to logo
`name`	Name of the company

Logo API

If you’re only interested in a Company’s logo, and don’t need any other data about the company, you can use our free Logo API.

Access to the API is unauthenticated and doesn’t require a Clearbit account. We also provide some nify options listed below. If we can’t find a logo we’ll return a 404 status.

You can call the API directly from an html img tag - images are returned inline. For example:

<img src="https://logo.clearbit.com/stripe.com">

Return’s Stripe’s logo.

To alter the size or greyscale, pass some query params:

<img src="https://logo.clearbit.com/stripe.com?size=200&greyscale=true">

HTTP Request

GET https://logo.clearbit.com/:domain

Where :domain is the domain of the company.

HTTP GET params

You can also optionally pass us the following parameters.

param	Description
`size`	integer (optional) image size: length of longest side in pixels (default is `128`)
`format`	string (optional) image format, either `"png"` or `"jpg"` (defaults to `png`)
`greyscale`	boolean (optional) Desaturates image if passed (defaults to `false`)

Default images

Sometimes we can’t find a logo and image requests will return with a 404 response code. Rather than having a broken image show up you can use the onerror event to replace the image with a default of your choosing.

We’ve put together an example of how to do this with both jQuery and pure JavaScript.

Specifying your own logo

Specify your own logo with the og:logo Open Graph tag.

<meta property="og:logo" content="http://yourdomain.com/logo.png" />

Or to specify different sizes add multiple meta tags with a size attribute.

<meta property="og:logo" content="/logo.png" size="150x150" />
<meta property="og:logo" content="/logo.png" size="250x250" />
<meta property="og:logo" content="/logo.png" size="500x500" />

While we normally try and detect a company’s logo using signals like their Twitter or Facebook account, if you control a domain you can indicate which logo you’d like used.

Just add a og:logo Open Graph meta tag to your index page under the root domain, and point its content attribute to your logo of choice. We support png and jpg formats.

* Commercial use of the Logo API requires a link attribution on any page in which the logo is displayed - i.e “Logos provided by Clearbit”. See our terms for more info.