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@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 integer 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.

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

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

The Prospector V2 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.

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.

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, 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.

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 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": "54.157.61.194",
  "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=54.157.61.194' \
        -u {key}:
Clearbit::Reveal.find(
  ip: '54.157.61.194'
)
result = clearbit.Reveal.find(
  ip='54.157.61.194'
)

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

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