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

Person search

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

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

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

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

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

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

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

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

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

HTTP Request

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

HTTP GET params

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

param	Description
`domain`	string Domain of the company you want to search for. (required)
`role`	string The person’s standardized role at the company they work for based on their title. See all possible values. (optional)
`roles[]`	string Multiple roles to filter by. You can specify this parameter multiple times to search for multiple roles. (optional)
`seniority`	string The person’s standardized seniority at the company they work for based on their title. See all possible values. (optional)
`seniorities[]`	string Multiple seniorities to filter by. You can specify this parameter multiple times to search for multiple seniorities. (optional)
`title`	string The person’s title at the company they work for. (optional)
`titles[]`	string Multiple job titles to filter by. You can specify this parameter multiple times to search for multiple titles. (optional)
`city`	string The city the person lives in. (optional)
`cities[]`	string Multiple cities to filter by. You can specify this parameter multiple times to search for multiple cities. (optional)
`state`	string The state the person lives in. (optional)
`states[]`	string Multiple states to filter by. You can specify this parameter multiple times to search for multiple states. (optional)
`country`	string The country the person lives in. (optional)
`countries[]`	string Multiple countries to filter by. You can specify this parameter multiple times to search for multiple countries. (optional)
`name`	string The person’s name. (optional)
`query`	string (optional) Search query string. (optional)
`page`	integer Which results page to show (default is `1`).
`page_size`	integer The amount of results to return per page (default is `5`, max is `20`).
`suppression`	string Set to `eu` to exclude records with country data in the EU. Set to `eu_strict` to exclude records with country data in the EU or with null country data. (optional)

Response Types

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

Response body

The JSON encoded response looks like this:

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

Every search response includes the following four fields:

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

Person Attributes

Attribute	Description
`id`	string Internal ID
`name.givenName`	string The person’s first name.
`name.familyName`	string The person’s last name.
`name.fullName`	string The person’s full name.
`title`	string The person’s title at the company they work for.
`role`	string The person’s standardized role at the company they work for based on their title. See all possible values.
`subRole`	string The person’s standardized sub role at the company they work for based on their title. See all possible values.
`seniority`	string The person’s standardized seniority at the company they work for based on their title. See all possible values.
`company.name`	string The name of the company the person works for.
`email`	string The person’s email.
`verified`	boolean Indicates whether the person’s match was exact or not.
`phone`	string The person’s phone number.

Queries

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

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

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

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

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

Data types

Every query option is one of the following data types:

type	Description
`string`	Letters

Fields

The following fields are supported:

Param	Description
`name`	string The person’s name.
`role`	string The person’s standardized role at the company they work for based on their title. See all possible values.
`title`	string The person’s title at the company they work for.
`seniority`	string The person’s standardized seniority at the company they work for based on their title. See all possible values.
`state`	string The state the person lives in.
`country`	string The country the person lives in.
`and`	query AND query (further details below)
`or`	query OR query (further details below)
`not`	query NOT query (further details below)

AND/OR/NOT queries

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

  or:(name:Alex city:"San Francisco")

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

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

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

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

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

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

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

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

Negation works by prefixing a query with not:

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

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

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

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

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

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

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

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

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

Nesting works by including additional queries inside the parentheses:

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

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

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

Queries can be also be nested within one another.

Prospector V2 API (beta)

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 in beta and only available under our Enterprise plans.
To get access to the API, please contact us.

Person search

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

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

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

HTTP Request

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

HTTP GET params

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

param	Description
`domains[]`	string One or more domains for the companies you are searching for.
`names[]`	string One or more person names to filter by.
`roles[]`	string One or more employment roles to filter by. (view list)
`seniorities[]`	string One or more employment seniorities to filter by. (view list)
`titles[]`	string One or more job titles to filter by.
`locations[]`	string One or more person locations to filter by.
`cities[]`	string One or more person cities to filter by.
`states[]`	string One or more person states to filter by.
`countries[]`	string One or more person countries to filter by.
`company_cities[]`	string One or more company cities to filter by.
`company_states[]`	string One or more company states to filter by.
`company_countries[]`	string One or more company countries to filter by.
`employees_ranges[]`	string One or more company employee ranges to filter by.
`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.
`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": "34.229.63.28",
  "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=34.229.63.28' \
        -u {key}:

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

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

print result

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

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

Specifying your own logo

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

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

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

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

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

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