Versioning

Versioning

When making direct API requests in URL, you can specify the API version within the URL. We will continue to support older versions of the APIs until we deem its usage is too small to maintain, at which point we will send remaining customers a 30-day (minimum) warning of this.

Our goal is to never break functionality on an existing API endpoint. When we make backwards-incompatible changes to the APIs or to a dataset, we'll create a new version. The most up-to-date version of the APIs is v5. The next version of the APIs will be v6. We perform batch data builds on a quarterly basis. We don't perform any streaming updates to the dataset between data releases. Each version of the APIs will use the most up-to-date data release.

You can view our Example Record to better understand the Person Data Schema, though each API endpoint will have its own unique response. Data releases happen every three months between the first and fifteenth of the first month of the fiscal quarter. After a data release, barring a significant update that breaks existing functionality in the APIs, we will return the newly built data in existing versions of the APIs. Therefore, the dataset is not completely static; the number of fields and data points that a specific profile has may increase or decrease through time.

In a single API version, we make persistence commitments in our Person Manual relating to certain fields.

Endpoints

All API endpoints follow the standard format: /version/entity/product.

Version (as explained above) is the version of our API endpoint, which will never have breaking functionality changes. Breaking changes, such as a new schema, will only occur when we convert to a new endpoint.

Entity is the type of data handled by the API. The core data model we focus on is person data. However, we also have company, location and school data.

Product is a distinguishing tag, as we have multiple endpoints for each entity. For example, we currently have an enrichment and a search endpoint for the person endpoint.


Did this page help you?