Streaming and more

Streaming and more

September 19, 2014

We're excited to announce some new API features based on some of the feedback we've received from our customers.

Streaming

Some of our endpoints respond asynchronously. For example, when we look up an email, if we haven't cached the lookup, we'll need to go out and search our indexes. This can take in the region of five to ten seconds.

If we have to respond to a lookup asynchronously then we'll return a HTTP status 202 code and ask you to either retry the request later or use our webhook API.

However, sometimes it's not an issue if requests to Clearbit take a while. Say for example you're calling our API from a messaging queue. This is where our new streaming API comes in. We'll keep the request connection hanging open (up to sixty seconds) until we receive some data.

The streaming API is fully explained in our docs, but to use it just requires replacing the original API subdomain with our streaming one. For example:

# Change person.clearbit.co
curl 'https://person.clearbit.co/v1/people/email/alex@clearbit.co'

# To person-stream.clearbit.co
curl 'https://person-stream.clearbit.co/v1/people/email/alex@clearbit.co'

Similarly in our client bindings just swap out the classes:

# Normal API
Clearbit::Person[email: 'alex@clearbit.co']

# Streaming API
Clearbit::Streaming::Person[email: 'alex@clearbit.co']

Company

Many of our customers were having to do two API calls when looking up email addresses: one API call to look up the email and another to lookup the company based on the email's domain.

We now do a Company API lookup by default on all email lookups using the email addresses' domain name. This is included in the Person API response.

Employment

We also now return employment information on people when we can find it. This includes the person's employer name, domain and their job title. For example:

curl 'https://person.clearbit.co/v1/people/email/lachy@stripe.com'

  {
    "id": "e88c903d-5d66-4279-b180-3d73c56b27ab",
    "name": {
      "fullName": "Lachy Groom",
      "givenName": "Lachy",
      "familyName": "Groom"
    },
    "employment": {
      "name": "Stripe",
      "title": "International Operations",
      "domain": "stripe.com"
    }
    // ...
  }

Fuzzy match

Sometimes we have a pretty good idea of who the person related to an email address is, but we can't be totally sure. This is where the new fuzzy attribute comes in.

When we can't do an exact email match on a person the returned fuzzy attribute will be true. In all other cases it'll be false.

curl 'https://person.clearbit.co/v1/people/email/john@example.com'

  {
    "name": {
      "fullName": "John Doe",
      "givenName": "John",
      "familyName": "Doe"
    },
    "fuzzy": true,
    // ...
  }

We added these features based on your feedback--if you've got other suggestions we'd love to hear from you.


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 https://logo.clearbit.com/:domain 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.

Join our newsletter

Engaging stories and exclusive data, designed for our best customers. One useful issue each month.