Domain aliases and more

Domain aliases and more

June 01, 2015

We've been busy improving our APIs based on your feedback, and I'm excited to announce a few additions we've just shipped.


The biggest change is the addition of versioning to our APIs. We use a date based version which you can pass through in a API-Version header when making API requests.

curl '' \
        -H 'API-Version: 2015-05-11'

All of our clients support setting a version. For example with our Ruby library:

Clearbit::Person.version = '2015-05-11'

Your default API version will be set whenever you first make an API request. You can upgrade versions on a request-by-request basis by providing a header as above, or by upgrading globally in your dashboard. More information about versioning is available in our docs.

Combined webhook

Our combined lookup API returns person and company information based on an email address. Previously calls to this endpoint would trigger two webhook requests, separate person and company webhooks.

That behavior was far from ideal from a development perspective so we've shipped support for combined person & company webhooks. Calls to the combined API will now return one webhook containing all the information.

This was a breaking change so it's under a new API version: 2015-04-30. You can upgrade your API version in the dashboard.

Domain aliases

Companies often have a quite a few domains, especially if they've changed names in the past. For example, Airbnb used to use the domain, a domain that now forwards to

We've now added redirection support to our Company API so any redirects will be followed and return the correct information. We'll even return a list of aliased domains that we've detected the company also owns under a domainAliases property.

For example, a lookup of now returns:

curl ''

      "id": "3813b002-8d0e-44d0-b6cb-5bb3222a03db",
      "name": "Facebook",
      "legalName": "Facebook, Inc.",
      "domain": "",
      "domainAliases": [

Company type

We've added a new type attribute for Company lookups which specifies what kind of company we're returning.

  • private - Private business
  • public - Publicly listed company
  • nonprofit - Nonprofit or charity
  • government - Government organization
  • education - Educational institution (such as a university)
  • personal - Personal website (not a company)

This should be particularly useful for partitioning leads, especially if your focus is on a particular market (like universities).

Secure webhooks

It's important to be sure that any webhooks you receive from Clearbit are really from us. We've now added a X-Request-Signature header to webhook requests containing a HMAC of the webhook's contents signed with your API key.

If you're using the Ruby API we'll check this signature automatically and raise an exception if there's a mismatch.

post '/v1/webhooks/clearbit' do
    webhook =
    webhook.type #=> 'person' #=> 'Alex'

    # ...
  rescue Clearbit::Errors::InvalidWebhookSignature => e
    # ...

For more information on how to verify these signatures, please see our docs.

Always improving

All of these features came directly from customer requests, so if there's something you're itching to see in Clearbit please don't hesitate to get in touch.

Company Logo API

Engineeringby Alex MacCaw on January 01, 2021

Clearbit's free Logo API is still available here in 2021 — and still completely free. We never found anything that catered well to company logos. And yet there's a lot of clear use-cases ranging from setting an organization's default image on signup to pulling in logos next to job listings. Clearbit Logo API The API is incredibly simple, taking a company's domain and returning an image. GET Behind the scenes we're using Clearbit's Company API [https://clear

Introducing ultimate parent to Clearbit Enrichment API

Engineeringby Emily Brown on April 16, 2019

We've added a new data attribute to Clearbit's Company Enrichment API: ultimate parent. Bring full context of your accounts' hierarchy into view — so your team can stay up to speed on new acquisitions and know when they're in conversation with the same parent company.

The Standard in B2B Data

Now reinvented with Artificial Intelligence—Clearbit is the first AI Native Data Provider. Enrich your records, reveal buying intent, and connect with your ideal customers.