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:

• Ruby
• Node
• Python
• Go
• Java

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@clearbit.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@clearbit.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 15 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@clearbit.com', stream: true)

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

curl 'https://person-stream.clearbit.com/v1/people/email/alex@clearbit.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@clearbit.com', stream=True)
if person != None:
  print "Name: " + person['name']['fullName']

Or to look up a company:

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

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

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

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

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

company = clearbit.Company.find(domain='clearbit.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, connect with our partnerships team.

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 usage 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. Your usage period is monthly or annually, rolling based on your start date. To find your usage period, please visit this page and review the ‘Current Period Usage’ table.

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 The person’s first name.
family_name	string The person’s last name. If you have this, passing this is strongly recommended to improve match rates.
ip_address	string The person’s IP address. If you have this, passing this is strongly recommended to improve match rates.
location	string The city or country where the person lives.
company	string The name of the company the person works for.
company_domain	string The domain of the company the person works for.
linkedin	string The person’s LinkedIn profile URL.
twitter	string The person’s Twitter profile username.
facebook	string The person’s Facebook profile URL.
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@clearbit.com",
  "location": "San Francisco, CA, US",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -7,
  "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",
    "id": "2142",
    "avatar": "https://avatars.githubusercontent.com/u/2142?v=2",
    "company": "Clearbit",
    "blog": "http://alexmaccaw.com",
    "followers": 3594,
    "following": 111
  },
  "twitter": {
    "handle": "maccaw",
    "id": "2006261",
    "bio": "O'Reilly author, software engineer & traveller. Founder of https://clearbit.com",
    "followers": 15248,
    "following": 1711,
    "statuses": 14300,
    "favorites": 21100,
    "location": "San Francisco",
    "site": "http://alexmaccaw.com",
    "avatar": "https://pbs.twimg.com/profile_images/1826201101/297606_10150904890650705_570400704_21211347_1883468370_n.jpeg"
  },
  "linkedin": {
    "handle": "in/alex-maccaw-ab592978"
  },
  "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",
  "phone": "+1 123-456-7890",
  "activeAt": "2014-11-25T18:56:43.000Z",
  "inactiveAt": "2021-11-25T18:56:43.000Z"
}

Attribute	Description
id	string Clearbit’s internal identifier for the person.
name.givenName	string The person’s first name.
name.familyName	string The person’s last name.
name.fullName	string The person’s full name. This may exist even if the givenName or familyName aren’t available.
email	string The person’s email.
location	string The city, state, and country where the person lives.
timeZone	string The person’s time zone based on their location. See all possible values.
utcOffset	integer The difference in hours from the person’s time zone to UTC (-12 to 14).
geo.city	string The city the person lives in based on their location.
geo.state	string The state the person lives in based on their location.
geo.stateCode	string The state code of the state the person lives in based on their location.
geo.country	string The country the person lives in based on their location.
geo.countryCode	string The country code of the country the person lives in based on their location.
geo.lat	float The latitude based on the person’s location.
geo.lng	float The longitude based on the person’s location.
bio	string The person’s bio surfaced through their own social media accounts.
site	string The person’s website surfaced through their own social media accounts.
avatar	string The person’s profile picture surfaced through their own social media accounts.
employment.domain	string The domain of the company the person works for.
employment.name	string The name of the company the person works for.
employment.title	string The person’s title at the company they work for.
employment.role	string The person’s standardized role at the company they work for based on their title. See all possible values.
employment.subRole	string The person’s standardized sub role at the company they work for based on their title. See all possible values.
employment.seniority	string The person’s standardized seniority at the company they work for based on their title. See all possible values.
facebook.handle	string The person’s Facebook profile username (e.g. amaccaw).
github.handle	string The person’s GitHub profile username (e.g. maccman).
github.id	string The ID of the person’s GitHub profile.
github.avatar	string The profile picture of the person’s GitHub profile.
github.company	string The company the person works for as listed on their GitHub profile.
github.blog	string The person’s website as listed on their GitHub profile.
github.followers	string The number of followers the person has on GitHub.
github.following	string The number of people the person follows on GitHub.
twitter.handle	string The person’s Twitter profile username (e.g. maccaw).
twitter.id	integer The ID of the person’s Twitter profile.
twitter.bio	string The person’s bio as listed on their Twitter profile.
twitter.followers	integer The number of followers the person has on Twitter.
twitter.following	integer The number of people the person follows on Twitter.
twitter.statuses	integer The number of tweets the person has shared on Twitter.
twitter.favorites	integer The number of tweets the person has liked on Twitter.
twitter.location	string The person’s location as listed on their Twitter profile.
twitter.site	string The person’s website as listed on their Twitter profile.
twitter.avatar	string The profile picture of the person’s Twitter profile.
linkedin.handle	string The last section of the person’s LinkedIn profile URL (e.g. in/alex-maccaw-ab592978).
googleplus.handle	string The person’s Google Plus username. This field has been deprecated.
gravatar.handle	string The person’s Gravatar profile username (e.g. maccman).
gravatar.urls	array A list of websites listed by the person on their Gravatar profile.
gravatar.avatar	string The profile picture of the person’s Gravatar profile.
gravatar.avatars	string A list of pictures listed by the person on their Gravatar profile.
fuzzy	boolean Indicates whether the person’s search was fuzzy or an exact match.
emailProvider	boolean Indicates whether the person’s email domain is associated with a free email provider (e.g. Gmail). Useful for distinguishing between personal emails and work emails.
indexedAt	string date Timestamp indicating when the person’s record was last updated in Clearbit’s database. A record update may or may not include new information about the person.
phone	string The person’s phone number.
activeAt	string date Timestamp indicating when Clearbit detected the person’s email became active.
inactiveAt	string date Timestamp indicating when Clearbit detected the person’s email became inactive.

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 The person’s first name.
family_name	string The person’s last name. If you have this, passing this is strongly recommended to improve match rates.
ip_address	string The person’s IP address. If you have this, passing this is strongly recommended to improve match rates.
location	string The city or country where the person lives.
company	string The name of the company the person works for.
company_domain	string The domain of the company the person works for.
linkedin	string The person’s LinkedIn profile URL.
twitter	string The person’s Twitter profile username.
facebook	string The person’s Facebook profile URL.

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

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

clearbit.Person.find({email: 'clearbit.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@clearbit.com&subscribe=true' \
        -u {key}:

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

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

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

clearbit.Person.find(email='alex@clearbit.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@clearbit.com')
person.flag!(given_name: 'Alexander', employment_title: 'The Great')

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

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

person = clearbit.Person.find(email='alex@clearbit.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 The person’s first name. (optional)
family_name	string The person’s last name. (optional)
employment_title	string The person’s title at the company they work for. (optional)
facebook_handle	string (optional) The person’s Facebook profile username. (optional)
github_handle	string The person’s GitHub profile username. (optional)
twitter_handle	string The person’s Twitter profile username. (optional)
linkedin_handle	string The last section of the person’s LinkedIn profile URL (e.g. in/alex-maccaw-ab592978) (optional)
googleplus_handle	string The person’s Google Plus handle. (optional)

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": "a114c279-67aa-4faa-beaf-64246a856450",
  "name": "Clearbit",
  "legalName": "APIHub Inc",
  "domain": "clearbit.com",
  "domainAliases": [
    "clearbit.co",
    "clearbit.ca",
    "salesmarketingstack.com"
  ],
  "site": {
    "phoneNumbers": [
      "+1 866-241-4820",
      "+1 415-805-3400"
    ],
    "emailAddresses": [
      "privacy@clearbit.com",
      "legal@clearbit.com",
      "support@clearbit.com",
      "success@clearbit.com"
    ]
  },
  "category": {
    "sector": "Information Technology",
    "industryGroup": "Software & Services",
    "industry": "Internet Software & Services",
    "subIndustry": "Internet Software & Services",
    "gicsCode": "45102010",
    "sicCode": "73",
    "sic4Codes": ["7371"],
    "naicsCode": "54",
    "naics6Codes": ["541613", "541810"],
    "naics6Codes2022": ["541511"]
  },
  "tags": [
    "Information Technology & Services",
    "Technology",
    "SAAS",
    "B2B"
  ],
  "description": "The Clearbit Data Activation Platform helps B2B teams understand customers, identify prospects, & personalize interactions with real-time intelligence.",
  "foundedYear": 2015,
  "location": "90 Sheridan, San Francisco, CA 94103, USA",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -7,
  "geo": {
    "streetNumber": "90",
    "streetName": "Sheridan",
    "subPremise": null,
    "streetAddress": "90 Sheridan",
    "city": "San Francisco",
    "postalCode": "94103",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "lat": 37.77219420000001,
    "lng": -122.4118037
  },
  "logo": "https://logo.clearbit.com/clearbit.com",
  "facebook": {
    "handle": "clearbitinc",
    "likes": 10906
  },
  "linkedin": {
    "handle": "company/clearbit"
  },
  "twitter": {
    "handle": "clearbit",
    "id": "2857311332",
    "bio": "Hit your target, in any market. Get started at https://t.co/cUkmd7m8dI. Need help? Send questions to support@https://t.co/cUkmd7m8dI.",
    "followers": 4620,
    "following": 293,
    "location": "San Francisco",
    "site": "https://t.co/jdOiK41RjG",
    "avatar": "https://pbs.twimg.com/profile_images/1511018930155888643/GvNtOWok_normal.png"
  },
  "crunchbase": {
    "handle": "organization/clearbit"
  },
  "emailProvider": false,
  "type": "private",
  "ticker": null,
  "identifiers": {
    "usEIN": null
  },
  "phone": null,
  "metrics": {
    "alexaUsRank": 25360,
    "alexaGlobalRank": 49044,
    "trafficRank": "high",
    "employees": 190,
    "employeesRange": "51-250",
    "marketCap": null,
    "raised": 17000000,
    "annualRevenue": null,
    "estimatedAnnualRevenue": "$10M-$50M",
    "fiscalYearEnd": null
  },
  "indexedAt": "2023-04-05T01:30:08.146Z",
  "tech": [
    "contentful",
    "aws_route_53",
    "google_apps",
    "mutiny",
    "lever",
    "google_analytics",
    "customer_io",
    "hotjar",
    "facebook_advertiser",
    "google_tag_manager",
    "segment",
    "stripe",
    "appnexus",
    "dropbox",
    "openx",
    "mediamath",
    "okta",
    "mongodb",
    "pubmatic",
    "rubicon_project",
    "salesforce",
    "statcounter",
    "github",
    "quickbooks",
    "unbounce",
    "stackadapt",
    "postgresql",
    "mysql"
  ],
  "techCategories": [
    "content_management_system",
    "dns",
    "productivity",
    "applicant_tracking_system",
    "analytics",
    "marketing_automation",
    "website_optimization",
    "advertising",
    "tag_management",
    "customer_data_platform",
    "payment",
    "security",
    "database",
    "crm",
    "accounting_and_finance",
    "adverstising"
  ],
  "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 Clearbit’s internal identifier for the company.
name	string The company’s name.
legalName	string The company’s legal name.
domain	string The company’s website.
domainAliases	array A list of domains that redirect to the company’s main website.
site.phoneNumbers	array A list of phone numbers listed on the company’s website.
site.emailAddresses	array A list of email addresses listed on the company’s website.
category.sector	string The broadest tier of company industry classification. See all possible values.
category.industryGroup	string The second tier of company industry classification. See all possible values.
category.industry	string The third tier of company industry classification. See all possible values.
category.subIndustry	string The most specific tier of company industry classification. See all possible values.
category.gicsCode	string A list of 8 digit company Global Industrial Classification Standard (GICS) codes. See all possible values.
category.sicCode	string The two digit company Standard Industry Classification (SIC) code. See all possible values.
category.sic4Codes	array A list of primary and secondary four digit company Standard Industry Classification (SIC) codes. See all possible values.
category.naicsCode	string The two digit company North American Industry Classification System (NAICS) code. See all possible values.
category.naics6Codes	array A list of primary and secondary six digit company North American Industry Classification System (NAICS) 2017 codes. See all possible values.
category.naics6Codes2022	array A list of primary and secondary six digit company North American Industry Classification System (NAICS) 2022 codes. See all possible values.
tags	array A list of company vertical descriptors. Typically more granular than industry classification. See all possible values.
description	string The company’s description.
foundedYear	integer The year the company was founded.
location	string The company headquarters address.
timeZone	string The time zone of the company headquarters based on their location. See all possible values.
utcOffset	integer The difference in hours from the company’s time zone to UTC (-12 to 14).
geo.streetNumber	string The street number of the company headquarters based on their location.
geo.streetName	string The street name of the company headquarters based on their location.
geo.subPremise	string The suite number of the company headquarters based on their location.
geo.streetAddress	string The street address of the company headquarters based on their location.
geo.city	string The city of the company headquarters based on their location.
geo.postalCode	string The postal code of the company headquarters based on their location.
geo.state	string The state of the company headquarters based on their location.
geo.stateCode	string The state code of the company headquarters based on their location.
geo.country	string The country of the company headquarters based on their location.
geo.countryCode	string The country code of the company headquarters based on their location.
geo.lat	float The latitude of the company headquarters based on their location.
geo.lng	float The longitude of the company headquarters based on the their location.
logo	string The company’s logo.
facebook.handle	string The company’s Facebook page username (e.g. clearbitinc).
facebook.likes	integer The number of likes the company has on their Facebook page.
linkedin.handle	string The last section of the company’s LinkedIn page URL (e.g. company/clearbit).
twitter.handle	string The company’s Twitter profile username (e.g. clearbit).
twitter.id	string The ID of the company’s Twitter profile.
twitter.bio	string The company’s bio as listed on their Twitter profile.
twitter.followers	integer The number of followers the company has on Twitter.
twitter.following	integer The number of people the company follows on Twitter.
twitter.location	string The company’s location as listed on their Twitter profile.
twitter.site	string The company’s website as listed on their Twitter profile.
twitter.avatar	string The profile picture of the company’s Twitter profile.
crunchbase.handle	string The last section of the company’s Crunchbase profile page URL (e.g. organization/clearbit).
emailProvider	boolean Indicates whether the company’s email domain is associated with a free email provider (e.g. Gmail).
type	string The company’s type. See all possible values.
ticker	string The company’s stock symbol. This attribute is available for public companies only.
identifiers.usEIN	string The company’s US Employer Identification Number (EIN).
phone	string The company headquarters phone number.
metrics.alexaUsRank	integer The company’s standing in a US rank of company website traffic as calculated by Alexa. This field has been deprecated. Please use trafficRank instead.
metrics.alexaGlobalRank	integer The company’s standing in a global rank of company website traffic as calculated by Alexa. This field has been deprecated. Please use trafficRank instead.
metrics.trafficRank	string The company’s standing in a global rank of company website traffic as calculated by Clearbit. See all possible values.
metrics.employees	integer The total number of employees that work at the company.
metrics.employeesRange	string The number of employees that work at the company by range. Useful for segmenting companies by size. See all possible values.
metrics.marketCap	integer The company’s total market capitalization. This attribute is available for public companies only.
metrics.raised	integer The total amount of funding raised by the company.
metrics.annualRevenue	integer The company’s annual revenue. This attribute is available for public companies only.
metrics.estimatedAnnualRevenue	string An estimate of the company’s annual revenue by range. See all possible values.
metrics.fiscalYearEnd	integer The month that the company’s fiscal year ends (listed as integer 1-12).
indexedAt	string date Timestamp indicating when the company’s record was last updated in Clearbit’s database. A record update may or may not include new information about the company.
tech	array A list of technologies used by the company. See all possible values.
techCategories	array A list of technology categories used by the company. See all possible values.
parent.domain	string The domain of the company’s parent company (if any).
ultimateParent.domain	string The domain of the company’s ultimate parent company (if any).

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 company’s name.
linkedin	string The company’s LinkedIn page URL.
twitter	string The company’s Twitter profile username.
facebook	string The company’s Facebook page URL.

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: 'clearbit.com', company_name: 'Clearbit')

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=clearbit.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='clearbit.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=clearbit.com' \
        -d 'name=Clearbit' \
        -u {key}:

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

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

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

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

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 The company’s name. (optional)
tags	array A list of company vertical descriptors. Typically more granular than industry classification.
description	string The company’s description.
raised	integer The total amount of funding raised by the company.
location	string The company headquarters address.
facebook_handle	string The company’s Facebook page username (e.g. clearbitinc). (optional)
twitter_handle	string The company’s Twitter profile username. (optional)
linkedin_handle	string The last section of the company’s LinkedIn page URL (e.g. company/clearbit).
crunchbase_handle	string The last section of the company’s Crunchbase profile page URL (e.g. organization/clearbit).
employees	integer The total number of employees that work at the company.
logo	string The company’s logo.
email_provider	boolean Indicates whether the company’s email domain is associated with a free email provider (e.g. Gmail).
type	string The company’s type. Possible values are: education, government, nonprofit, private, public, or 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.

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	The company’s standing in a global rank of company website traffic as calculated by Alexa.
employees	The total number of employees that work at the company.
market_cap	The company’s total market capitalization. This parameter is available for public companies only.
raised	The total amount of funding raised by the company.
twitter_followers	The number of followers the company has on Twitter.

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 The exact company domain.
name	string A fuzzy company name.
description	string A fuzzy company description.
and	query AND query (further details below)
or	query OR query (further details below)
not	query NOT query (further details below)
alexa_rank	range The company’s standing in a global rank of company website traffic as calculated by Alexa.
alexa_us_rank	string The company’s standing in a US rank of company website traffic as calculated by Alexa.
location	string A fuzzy company headquarters address.
state	string The state of the company headquarters.
city	string The city of the company headquarters.
country	string The country of the company headquarters.
crunchbase	string The last section of the company’s Crunchbase profile page URL (e.g. organization/clearbit).
employees	range The total number of employees that work at the company.
facebook	string The company’s Facebook page username (e.g. clearbitinc).
founded_year	range The year the company was founded.
linkedin	string The last section of the company’s LinkedIn page URL (e.g. company/clearbit).
twitter	string The company’s Twitter profile username (e.g. clearbit).
twitter_followers	range The number of followers the company has on Twitter.
twitter_following	range The number of people the company follows on Twitter.
market_cap	range The company’s total market capitalization. This parameter is available for public companies only.
ticker	string The company’s stock symbol. This attribute is available for public companies only.
raised	range The total amount of funding raised by the company.
industry	string The third tier of company industry classification. See all possible values.
sub_industry	string The most specific tier of company industry classification. See all possible values.
sector	string The broadest tier of company industry classification. See all possible values.
tag	string A company vertical descriptor. Typically more granular than industry classification. See all possible values.
tech	string A technology used by the company. (further details below)
type	string The company’s type. Possible values are: education, government, nonprofit, private, public, or 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 possible technologies here.

Prospector API

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

Person search

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

people = Clearbit::Prospector.search(domain: 'clearbit.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: 'clearbit.com', 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='clearbit.com', role='leadership')

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

curl 'https://prospector.clearbit.com/v1/people/search' \
        -G --data-urlencode 'domain=clearbit.com' \
        --data-urlencode 'role=leadership' \
        -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 Domain of the company you want to search for. (required)
role	string The person’s standardized role at the company they work for based on their title. See all possible values. (optional)
roles[]	string Multiple roles to filter by. You can specify this parameter multiple times to search for multiple roles. (optional)
seniority	string The person’s standardized seniority at the company they work for based on their title. See all possible values. (optional)
seniorities[]	string Multiple seniorities to filter by. You can specify this parameter multiple times to search for multiple seniorities. (optional)
title	string The person’s title at the company they work for. (optional)
titles[]	string Multiple job titles to filter by. You can specify this parameter multiple times to search for multiple titles. (optional)
city	string The city the person lives in. (optional)
cities[]	string Multiple cities to filter by. You can specify this parameter multiple times to search for multiple cities. (optional)
state	string The state the person lives in. (optional)
states[]	string Multiple states to filter by. You can specify this parameter multiple times to search for multiple states. (optional)
country	string The country the person lives in. (optional)
countries[]	string Multiple countries to filter by. You can specify this parameter multiple times to search for multiple countries. (optional)
name	string The person’s name. (optional)
query	string (optional) Search query string. (optional)
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 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. (optional)

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 The person’s first name.
name.familyName	string The person’s last name.
name.fullName	string The person’s full name.
title	string The person’s title at the company they work for.
role	string The person’s standardized role at the company they work for based on their title. See all possible values.
subRole	string The person’s standardized sub role at the company they work for based on their title. See all possible values.
seniority	string The person’s standardized seniority at the company they work for based on their title. See all possible values.
company.name	string The name of the company the person works for.
email	string The person’s email.
verified	boolean Indicates whether the person’s match was exact or not.
phone	string The person’s phone number.

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 The person’s name.
role	string The person’s standardized role at the company they work for based on their title. See all possible values.
title	string The person’s title at the company they work for.
seniority	string The person’s standardized seniority at the company they work for based on their title. See all possible values.
state	string The state the person lives in.
country	string The country the person lives in.
and	query AND query (further details below)
or	query OR query (further details below)
not	query NOT query (further details 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.

Prospector V2 API

The Prospector V2 API lets you fetch contacts and emails based on a number of parameters related to their employment.

Person search

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

curl 'https://prospector.clearbit.com/v2/people/search' \
        -G --data-urlencode 'domains[]=twitter.com' \
        --data-urlencode 'roles[]=marketing' \
        -u {key}:

This endpoint returns an array of people who match certain search parameters.

HTTP Request

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

HTTP GET params

You can pass the following parameters along when searching for people. Parameters with [] can be specified multiple times to search for multiple values.

param	Description
domains[]	string One or more domains for the companies you are searching for.
names[]	string One or more person names to filter by.
roles[]	string One or more employment roles to filter by. (view list)
seniorities[]	string One or more employment seniorities to filter by. (view list)
titles[]	string One or more job titles to filter by.
locations[]	string One or more person locations to filter by.
cities[]	string One or more person cities to filter by.
states[]	string One or more person states to filter by.
countries[]	string One or more person countries to filter by.
company_cities[]	string One or more company cities to filter by.
company_states[]	string One or more company states to filter by.
company_countries[]	string One or more company countries to filter by.
employees_ranges[]	string One or more company employee ranges to filter by. Use the format min-max (ie, 1-10).
company_tags[]	string One or more company tags to filter by. (view list)
company_tech[]	string One or more company technologies to filter by. (view list)
company_types[]	string One or more company types to filter by. (view list)
industries[]	string One or more company industries to filter by. (view list)
revenue_ranges[]	string One or more company revenue ranges to filter by.
linkedin_profile_handles[]	string One or more LinkedIn profile handles to filter by.
business_models[]	string One or more company business models to filter by. (view list)
funding_raised_ranges[]	string One or more company funding ranges to filter by. Use the format min-max (ie, 1-10).
naics_codes[]	string One or more company 2 digit or 6 digit NAICS codes to filter by.
sic_codes[]	string One or more company 2 digit or 4 digit SIC codes to filter by.
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 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": 111,
  "results": [
    {
      "id": "f7c3d9694d3c52db2fba591e5bde102667548f9d2bd30c2d416f468fbdca299e",
      "name": {
        "fullName": "Alex MacCaw",
        "givenName": "Alex",
        "familyName": "MacCaw"
      },
      "avatar": "https://d2pbji6xra510x.cloudfront.net/v2/avatars/image",
      "location": "Fort Lauderdale, FL, United States",
      "linkedin": "in/alex-maccaw-ab592978",
      "employments": [
        {
          "company": "Clearbit",
          "email": "alex@clearbit.com",
          "domain": "clearbit.com",
          "linkedin": "company/clearbit",
          "title": "Chairman Of The Board",
          "role": "leadership",
          "subRole": "leadership",
          "seniority": "director",
          "startDate": "2020-11-01",
          "endDate": null,
          "present": true,
          "highlight": true
        },
        {
          "company": "Stripe",
          "email": null,
          "domain": "stripe.com",
          "linkedin": "company/stripe",
          "title": "Engineer",
          "role": "engineering",
          "subRole": "software_engineer",
          "seniority": "senior",
          "startDate": "2012-01-01",
          "endDate": "2013-01-01",
          "present": false,
          "highlight": false
        }
      ],
      "emails": [
        {
          "address": "alex@clearbit.com",
          "type": "work"
        }
      ],
      "phones": [
        {
          "number": "+1 419-123-4567",
          "type": "work"
        }
      ]
    }
  ]
}

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.fullName	string Full formatted name of person
name.givenName	string First name of person
name.familyName	string Last name of person
avatar	string URL to avatar image
location	string Location of person
linkedin	string URL to LinkedIn profile
employments	array Array of employment attributes
emails	array Array of email attributes
phones	array Array of phone attributes

Employment Attributes

Attribute	Description
company	string Name of company
email	string Email address of person at company
domain	string Domain of company
linkedin	string LinkedIn handle of company
title	string Employment title
role	string Employment role (view list).
subRole	string Employment sub-role (view list).
seniority	string Employment seniority (view list).
startDate	string Start date of employment
endDate	string End date of employment
present	boolean Whether the person is currently employed at this company
highlight	boolean Whether this employment is the most relevant to the search parameters

Email Attributes

Attribute	Description
address	string Email address
type	string Type of email address

Phone Attributes

Attribute	Description
number	string Phone number
type	string Type of phone number

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.

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.

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, along with other attributes such as where the it’s located geographically and the employment details of the person using the 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.

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 address to a company, we’ll either flag it as belonging to an Internet Service Provider (ISP) or return a 404 HTTP status code.

Attributes

The JSON encoded response looks like this.

{
  "ip": "3.239.76.211",
  "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",
  "role": "leadership",
  "seniority": "executive"
}

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). Note for type=isp the API does not return domain or company data, but will return geoIP.
company	object A full company response.
geoIP	object An object containing location data for the lookup IP.
geoIP.city	string The city that this IP is located in.
geoIP.state	string The state that this IP is located in.
geoIP.stateCode	string The state code for this IP’s state.
geoIP.country	string The country that this IP is located in.
geoIP.countryCode	string The country code for this IP’s country.
confidenceScore	string Confidence scores
role	string The standardized role of the person using the IP. See all possible values.
seniority	string The standardized seniority of the person using the IP. See all possible values.

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=3.239.76.211' \
        -u {key}:

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

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

print result

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

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

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.

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

The Clearbit logo API is no longer available for new users. We recommend checking out Logo.dev as an alternative.