Versioning APIs

Versioning APIs

May 15, 2015

Versioning APIs is never fun but if you provide a public API it's something you'll almost certainly run up against eventually. At Clearbit we've just started adding breaking changes to our API and have had to start thinking about how we're going to approach versioning.

There seems to be a few main approaches that people have tried:

Use the URL

This is a fairly straightforward solution - simply add an incrementing version number in the URL and route different API versions to different endpoints. Segment, for example, takes this approach.


This is definitely the simplest approach, but quickly gets unruly if you need to make lots of API changes.

Use a header

Putting a version in the request header is another good solution depending on your use case. GitHub have gone down this path, with a custom Accept header.

Accept: application/vnd.github.v3+json

This approach is probably best for APIs like GitHub's that only create big breaking changes once in a blue moon.

Use a dynamic date

Stripe not only have a very extensive API, but also a fairly stringent definition of what constitutes a backwards incompatible change. Since their versions are changing so often, they've taken the rather novel approach of having a dynamic version based on the date you make your first request.

You can upgrade this version in Stripe's dashboard, or on a per-request level with a custom header. They also provide a convenient changelog.

Although this approach is more complex, it comes with a lot of advantages such as being able to quickly ship new API features without changing an endpoint, and also being able to easily see which customers are using which versions of the API.

We've gone with this approach since we're anticipating quite a few changes to our APIs in the future as we improve them.

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.