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.
429 Too Many Requests The rate limit was exceeded.
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 or Reveal. 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. The Reveal API is not rate limited.

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: 2019-12-19' \
        -u {key}:

Clearbit::Person.version = '2019-12-19'

var clearbit = require('clearbit')('{key}');
clearbit.Person.setVersion('2019-12-19');

import clearbit

clearbit.Person.version = '2019-12-19'

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 2019-12-19
Company API 2019-12-19
Reveal API 2019-12-19
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 Request Bin, 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: 'segment.com', stream: true)

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

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

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

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

company = clearbit.Company.find(domain='segment.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 (optional) URL to redirect users back to, which must start with your application’s default redirect URL.

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@clearbit.com' \
        -u {key}:

response = Clearbit::Enrichment.find(email: 'alex@clearbit.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@clearbit.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@clearbit.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@clearbit.com' \
        -u {key}:

response = Clearbit::Enrichment.find(email: 'alex@clearbit.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@clearbit.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@clearbit.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@clearbit.com",
    "//": "..."
  },
  "company": {
    "id": "c5a6a9c5-303a-455a-935c-9dffcd2ed756",
    "name": "Clearbit",
    "legalName": "APIHub, Inc",
    "domain": "clearbit.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.

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.
suppression string Set to eu to exclude person records with country data in the EU. Set to eu_strict to exclude person records with country data in the EU or with null country data.

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",
  "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": "Co-founder, CEO",
    "role": "leadership",
    "subRole": "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
  },
  "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
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.subRole string Sub-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
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.

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: 'segment.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.
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.

Response Types

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

Subscribe

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.

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": {
    "phoneNumbers": [],
    "emailAddresses": [
      "domains@uber.com"
    ]
  },
  "category": {
    "sector": "Information Technology",
    "industryGroup": "Software & Services",
    "industry": "Internet Software & Services",
    "subIndustry": "Internet Software & Services",
    "sicCode": "47",
    "naicsCode": "51"
  },
  "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,
  "identifiers": {
    "usEIN": "452647441"
  },
  "phone": null,
  "indexedAt": "2016-11-07T00:00:00.000Z",
  "metrics": {
    "alexaUsRank": 544,
    "alexaGlobalRank": 943,
    "trafficRank": "high",
    "employees": 20313,
    "employeesRange": "10k-50k",
    "marketCap": null,
    "raised": 10610000000,
    "annualRevenue": null,
    "estimatedAnnualRevenue": "$1B-$10B",
    "fiscalYearEnd": 12
  },
  "tech": [
    "optimizely",
    "tealium",
    "atlassian_confluence",
    "workday",
    "talend",
    "oracle_peoplesoft",
    "salesforce",
    "teradata",
    "apache_kafka",
    "aws_dynamodb",
    "grafana",
    "factset",
    "dropbox"
  ],
  "techCategories": [
    "analytics",
    "advertising",
    "productivity",
    "human_capital_management",
    "data_management",
    "business_management",
    "crm",
    "monitoring"
  ],
  "parent": {
    "domain": null
  },
  "ultimateParent": {
    "domain": null
  }
}

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.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)
category.sicCode string Two digit category SIC code
category.naicsCode string Two digit category NAICS code
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
identifiers.usEIN string US Employer Identification Number
metrics.raised integer Total amount raised
metrics.alexaUsRank integer deprecated, please use TrafficRank
metrics.alexaGlobalRank integer deprecated, please use TrafficRank
metrics.trafficRank string Bucketed ranking of company site traffic as calculated by Clearbit’s proprietary algorithm
metrics.employees integer Amount of employees
metrics.employeesRange string Employees range (see a complete list)
metrics.marketCap integer Market Cap
metrics.annualRevenue integer Annual Revenue (public companies only)
metrics.estimatedAnnualRevenue string Estimated annual revenue range (see a complete list)
metrics.fiscalYearEnd integer Month that the fiscal year ends (1-indexed)
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
techCategories array Array of technology categories used by the company
parent.domain string The domain of the parent company (if any)
ultimateParent.domain string The domain of the ultimate parent company (if any)
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: 'segment.com', company_name: 'Segment, 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=segment.com' \
        -u {key}:
To lookup a company by domain name, run the following. 
var clearbit = require('clearbit')('{key}');
var Company = clearbit.Company;

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='segment.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/v2/companies/flag' \
        -XPOST \
        -d 'domain=segment.com' \
        -d 'name=Segment' \
        -u {key}:

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

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

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

company = clearbit.Company.find(domain='segment.com')
company.flag(name='Segment')

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/v2/companies/flag?domain=:domain

Where :domain is the domain 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 only available under our Enterprise plans.
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. You can only paginate through the first 10K results at this time.

Sorting

To sort by a specific attribute using 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}:

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
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)
not query NOT query (see below)
alexa_rank range Global Alexa rank
alexa_us_rank string US Alexa 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
founded_year range Year company was founded
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)
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/NOT 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}:

Negation works by prefixing a query with not:

  not:(tech:google_analytics type:public)

For example, to find all companies that are not public and don’t use Google Analytics:

Clearbit::Discovery.search(
query: {not: [{tech: 'google_analytics'}, {type: 'public'}]}
)

clearbit.Discovery.search(
query={'not': [{'tech': 'google_analytics'}, {'type': 'public'}]}
)

clearbit.Discovery.search({query: {not: [{tech: 'google_analytics'}, {type: 'public'}]}})
  .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=not:(tech:google_analytics type:public)' \
  -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. You can change this behavior to OR matching (where matches to all criteria are preferred, but not required) by using a OR query.

The NOT logical operator can also be used to negate any query.

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 domain, we also detect any technologies the company uses internally and for its websites. We then surface over 500 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, job title, and location.

The Prospector API is only available under our Enterprise plans.
To get access to the API, please contact us.

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.results.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.
city string (optional) City to filter by.
cities[] string (optional) Multiple cities to filter by. You can specify this param multiple times to search for multiple cities.
state string (optional) State to filter by.
states[] string (optional) Multiple states to filter by. You can specify this param multiple times to search for multiple states.
country string (optional) Country to filter by.
countries[] string (optional) Multiple countries to filter by. You can specify this param multiple times to search for multiple countries.
name string (optional) Name of an individual to filter by.
query string (optional) Search query string.
page integer Which results page to show (default is 1).
page_size integer The amount of results to return per page (default is 5, max is 20).
suppression string(optional) 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.

Response Types

Code Description
200 Successful lookup, person encoded in the response body.
422 Validation error or Too many results requested. Limited to a maximun of 200 results.

Response body

The JSON encoded response looks like this:

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

Every search response includes the following four fields:

Name Description
page Page number for pagination
page_size Number of results per page
total Total amount of people matching the search
results Array of person attributes

Person Attributes

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).
subRole string Employment sub-role (view list).
seniority string Employment seniority (view list).
company.name string Name of Company
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)

Queries

Queries are space separated key colon values. For example to find people in a leadership role, at the executive level, and based in SF the query would look like this:

  role:leadership seniority:executive city:"San Francisco"

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

  and:(name:Alex city:"Boston")

Queries to the Prospector 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

Fields

The following fields are supported:

Param Description
name string Person’s name
role string Job role
title string Job title
seniority string Job seniority
city string Long form city name
state string Two letter state code or full state name
country string Two letter country code or full country name
and query AND query (see below)
or query OR query (see below)
not query NOT query (see below)

AND/OR/NOT 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:(name:Alex city:"San Francisco")

For example, to find all people that are at a manager seniority or leadership role:

people = Clearbit::Prospector.search(domain: 'twitter.com', query: 'or:(seniority:manager role:leadership)')

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

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

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

people = clearbit.Prospector.search(domain='twitter.com', query='or:(seniority:manager role:leadership)')

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

curl 'https://prospector.clearbit.com/v1/people/search' \
  --data-urlencode 'query=or:(seniority:manager role:leadership)' \
  -G -u {key}:

Negation works by prefixing a query with not:

  not:(city:"San Francisco" role:sales)

For example, to find all people that are not in SF or a sales role:

people = Clearbit::Prospector.search(domain: 'twitter.com', query: 'not:(city:"San Francisco" role:sales)')

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

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

clearbit.Prospector.search({domain: 'twitter.com', query: 'not:(city:"San Francisco" role:sales)'})
  .then(function (people) {
    people.results.forEach(function(person){
      console.log(person.name.fullName, person.title);
    });
  })
  .catch(function (err) {
    console.error(err);
  });

people = clearbit.Prospector.search(domain='twitter.com', query='not:(city:"San Francisco" role:sales)')

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

curl 'https://discovery.clearbit.com/v1/companies/search' \
  --data-urlencode 'not:(city:"San Francisco" role:sales)' \
  -G -u {key}:

Nesting works by including additional queries inside the parentheses:

  and:(city:"San Francisco" or:(role:leadership seniority:executive))

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

The NOT logical operator can also be used to negate any query.

Queries can be also be nested within one another.

Risk API

Our Risk API takes an email and IP and calculates an associated risk score. This is especially useful for figuring out whether incoming signups to your service are spam or legitimate, or whether a payment has a high chargeback risk.

We’ll indicate if a particular email is disposable, undeliverable, or looks fake. We’ll also show you whether an IP address is blacklisted or is using a proxy. Lastly we’ll give you an overall risk score which you can use to take action, such as making suspicious signups complete additional steps like filling in a captcha or confirming their phone number.

Our integration docs will take you step by step through using the API, and we’ve also put together some example apps in Ruby, Node and Python. Otherwise the full API docs below will get you started.

The Risk API is distributed as a free tool, and is not as maintained as Clearbit core APIs.

JavaScript library

Place the following JavaScript snippet on your checkout and/or signup pages:

<script>
  !function(){
    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://risk.clearbit.com/v1/risk.js';
    var parent = document.getElementsByTagName('script')[0];
    parent.parentNode.insertBefore(script, parent);
  }();
</script>

There are two components to the Risk API: a HTTP REST API and a JavaScript library. Using the JS library in conjunction with the REST API is required to generate risk scores.

Place the piece of JavaScript referenced to the right on your checkout or signup page (before you make a request to our REST API).

Calculate scores

You can ping the Risk REST API with an email & IP address to calculate a risk score. We’ll also return some information about the parameters, for example indicating if the email is disposable or the IP belongs to a proxy.

For testing, you can provide the loopback IP address 127.0.0.1. That’ll switch off some of the things we do that don’t make sense in a testing environment like velocity checks.

Before you start calculating scores, make sure you’ve first integrated the JavaScript snippet as directed above. (Note: not including the snippet will result in invalid Risk scores.)

Attributes

The dot notation indicates that the property is one level deep inside a hash.

The JSON encoded response looks like this.

{
  "id": "8ea0c9e6-ff59-4506-9c3c-a79ead14ba1f",
  "live": true,
  "fingerprint": false,
  "email": {
    "valid": true,
    "socialMatch": true,
    "companyMatch": true,
    "nameMatch": true,
    "disposable": false,
    "freeProvider": false,
    "blacklisted": false
  },
  "address": {
    "geoMatch": null
  },
  "ip": {
    "proxy": false,
    "geoMatch": false,
    "blacklisted": false,
    "rateLimited": false
  },
  "risk": {
    "level": "high",
    "score": 100,
    "reasons": [
      "email_ip_geo_mismatch",
      "ip_country_greylisted",
      "no_fingerprint_match"
    ]
  }
}
Attribute Description
id string Internal Clearbit request ID
live boolean Whether or not we’re in live mode (i.e. not using a loopback IP)
fingerprint boolean Whether or not we got a fingerprint match.
email.valid boolean Email is syntatically valid & MX servers are present
email.socialMatch boolean Email has an associated social profile & presence
email.companyMatch boolean The email’s domain has a company associated with it
email.nameMatch boolean Email’s social profile name matches supplied name
email.disposable boolean Email is from a disposable provider (e.g. Mailinator)
email.freeProvider boolean Email is from a free provider (e.g. Gmail)
email.blacklisted boolean Email has been blacklisted (i.e. flagged multiple times)
address.geoMatch boolean Supplied country_code matches the country associated with the email
ip.proxy boolean IP address belongs to a proxy server
ip.geoMatch boolean IP address’s location matches that of the email
ip.blacklisted boolean IP address has been blacklisted (i.e. flagged multiple times)
ip.rateLimited boolean IP address has been ratelimited (i.e. used multiple times)
risk.level string Risk level, either low, medium, or high
risk.score integer Risk score out of 100
risk.reasons array Array of reasons which will give you an indication about how we’ve calculated a given score.

HTTP Request

To calculate a risk score for a person, run the following: 
curl https://risk.clearbit.com/v1/calculate \
        -d 'email=alex@clearbit.com' \
        -d 'name=Alex MacCaw' \
        -d 'ip=127.0.0.1' \
        -u {key}:

begin
  result = Clearbit::Risk.calculate(
    email: 'alex@clearbit.com',
    name:  'Alex MacCaw',
    ip:    '127.0.0.1'
  )

  if result.risk.level == 'high'
    # Reject user
  end
rescue Nestful::Error
  # In case of network/server errors
end

result = clearbit.Risk.calculate(
  email='alex@clearbit.com',
  name=Alex MacCaw,
  ip='127.0.0.1'
)

print result

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

clearbit.Risk.calculate({
    email: 'alex@clearbit.com',
    name: 'Alex MacCaw',
    ip: '127.0.0.1'
  })
  .then(function (result) {
    console.log('Result', result);
  })
  .catch(function (err) {
    console.error(err);
  });

POST https://risk.clearbit.com/v1/calculate

HTTP POST params

The following parameters are supported.

Param Description
email string (required) Email address to calculate score against
ip string (required) IP address to calculate score against
country_code string (strongly recommended) Person’s two letter country code
zip_code string (strongly recommended) Person’s postal/zip code
given_name string (strongly recommended) Person’s first name
family_name string (strongly recommended) Person’s last name
name string (optional) Alternative to passing in a separate given_name and family_name

Flagging

If you do come across bad actors, then you can help us improve our detection algorithms and risk scores by flagging them.

HTTP Request

To flag a person, run the following: 
curl https://risk.clearbit.com/v1/flag \
        -d 'type=spam' \
        -d 'email=bad.person@gmail.com' \
        -d 'ip=127.0.0.1' \
        -u {key}:

Clearbit::Risk.flag(
  type:  'spam',
  email: 'bad.person@gmail.com',
  ip:    '127.0.0.1'
)

result = clearbit.Risk.flag(
  type='spam',
  email='bad.person@gmail.com',
  ip='127.0.0.1'
)

print result

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

clearbit.Risk.flag({
    type:  'spam',
    email: 'bad.person@gmail.com',
    ip:    '127.0.0.1'
  })
  .then(function (result) {
    console.log('Result', result);
  })
  .catch(function (err) {
    console.error(err);
  });

POST https://risk.clearbit.com/v1/flag

HTTP POST params

The following parameters are supported.

Param Description
type string (required) Type of flag: either spam, chargeback, or other.
email string (required) Email address of bad actor
ip string (required) IP address of bad actor

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.

Currently we do not support IPv6 addresses, only IPv4 addresses.

The Reveal API is only available under our Enterprise plans.
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": "18.206.92.240",
  "fuzzy": true,
  "domain": "segment.com",
  "type": "company",
  "company": {
    "name": "Segment",
    "tags": [
      "Software",
      "SAAS",
      "B2B",
      "Information Technology & Services",
      "Technology",
      "Internet"
    ],
    "metrics": {
      "alexaUsRank": 14014,
      "alexaGlobalRank": 34096,
      "employees": 180,
      "employeesRange": "51-250",
      "raised": 108720000
    },
    "...":  "..."
  },
  "geoIP": {
    "city": "San Francisco",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US"
  },
  "confidenceScore": "very_high"
}

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 block, otherwise true.
domain string The matched company domain
type string The type of result (company, education, government, isp)
company object A full company response
geoIP object A object containing location data for lookup IP
geoIP.city string City that this IP is located in
geoIP.state string State that this IP is located in
geoIP.stateCode string State code for this IP’s state
geoIP.country string Country that this IP is located in
geoIP.countryCode string Country code for this IP’s country
confidenceScore string Confidence scores

Note: for type=isp the API does not return domain or company data.

Confidence Scores

Confidence scores indicate how confident we are that a matched IP address is accurate.

Confidence Description
very_high Significant activity in the past week, strong sustained use or public ARIN data
high Activity in the past month, sustained use
medium Activity in past 6 months, some sustained use
low Activity in past 12 months or noise from other companies

HTTP Request

To lookup an IP address, run the following: 
curl 'https://reveal.clearbit.com/v1/companies/find?ip=18.206.92.240' \
        -u {key}:

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

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

print result

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

clearbit.Reveal.find({
    ip: '18.206.92.240'
  })
  .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) IPv4 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.

Name To Domain API

The Company Name to Domain API lets you convert the exact name of a company to a website domain, and a logo.

We match based on exact company name, and return the company with the most website traffic. It’s worth noting, that since a company name is not a unique identifier, you should be prepared for some inherent inaccuracy in the results.

The Name To Domain API is distributed as a free tool, and is not as maintained as Clearbit core APIs.

HTTP Request

Send requests with the company name to the API:

curl 'https://company.clearbit.com/v1/domains/find?name=Segment' \
  -u {key}:

The JSON encoded response looks like this:

{
  "domain": "segment.com",
  "logo": "https://logo.clearbit.com/segment.com",
  "name": "Segment"
}

GET https://company.clearbit.com/v1/domains/find?name=:name

Where :name is the name of the company.

Response codes

Code Description
200 Successful lookup, result encoded in the response body.
404 Company not found.
422 Company name is invalid.

Params

The name param is required.

Param Description
name string (required) The name of the company.

HTTP Response

Responses will include the following three fields:

Name Description
domain Website domain of the company
logo URL to the logo of the company
name Name of the company

Autocomplete API

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

The Autocomplete API is distributed as a free tool, and is not as maintained as Clearbit core APIs.

Send requests with paritial company name to endpoint:

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

The JSON encoded response looks like this:

[
  {
    "name": "Segment",
    "domain": "segment.com",
    "logo": "https://logo.clearbit.com/segment.com"
  },
  {
    "name": "Segmentify",
    "domain": "segmentify.com",
    "logo": "https://logo.clearbit.com/segmentify.com"
  }
]

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 Logo API.

The Logo API is distributed as a free tool, and is not as maintained as Clearbit core APIs.

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

Using our Logo API requires a link back to clearbit.com on any page the logo is displayed. Attribution must be legible and use at least a 12-point font.

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

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

Return’s Segment’s logo.

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

<img src="https://logo.clearbit.com/segment.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.

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.