Join 15,000+ Subscribers
Get tactical growth tips once a week

Streaming and more

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.

Share this post
Join 15,000+ Subscribers
Get tactical growth tips once a week