Dealing with Deprecating APIs

Dealing with Deprecating APIs

September 21, 2015

From time to time we have to make backwards incompatible changes to our APIs. To make sure everything keeps working for our customers we have a date based API versioning system which works pretty well. However, this does mean that at any point in time we have a lot of customers using older versions of the API, which in turn means they're not getting the latest and greatest data from us.

We've been testing various approaches to persuade people to upgrade, some with more success than others.


Whenever we release a major new feature we email all our existing customers. Getting access to a new data attribute is often a big incentive for people, but unless they're actively in the process of integrating Clearbit emails are easily archived and forgotten about. Customers are wary of breaking something that's already working, so they often postpone upgrades indefinitely.


Our docs only reflect the latest version of the API, and after a couple of cases of people on older APIs getting very confused about mismatches between the docs and their live API we've added a big warning which is fairly hard to miss.

Docs notice


We always return the API version you're on with the X-API-Version response header, but today we've taken that a step further by including a X-API-Warn header for requests to deprecated APIs. Whenever we encounter this header in any of the API clients we print the contents to STDERR, which looks something like this:

WARNING! You are using a deprecated version of the API which may return less data.
For more information on upgrading see

The idea is that this message will appear in server logs prompting people to upgrade.

We're always searching for better ways to tackle this problem, so if you've any approaches that work come join us in the Slack room. Or even better come work with us!

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.