Domain aliases and more

|June 01, 2015|3 minute read

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

Versioning

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 'https://person.clearbit.com/v1/people/email/alex@clearbit.com' \
        -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 airbedandbreakfast.com, a domain that now forwards to airbnb.com.

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 fb.com now returns:

curl 'https://company.clearbit.com/v1/companies/domain/fb.com'

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

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
  begin
    webhook = Clearbit::Webhook.new(env)
    webhook.type #=> 'person'
    webhook.body.name.given_name #=> 'Alex'

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

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.