Versioning and deprecation
How the Kustomer API is versioned, how deprecations are marked, and how to build clients that keep working as the API grows.
The Kustomer API is versioned in the path. Nearly every endpoint is under /v1, and it evolves in place by adding to it. A new major version of an endpoint gets a new path, and the old one keeps working alongside it.
Path versions
The /v2 endpoints are listed in the Core resources v2 reference. When a /v2 endpoint exists, prefer it for new code.
Changes you should expect
The API grows without a version bump. Build your client to tolerate these:
- New endpoints and new optional request fields.
- New attributes in responses. Ignore fields you don't recognize instead of failing validation.
- New enum values, such as a new message
channelor event type. Handle unknown values gracefully, for example by logging and skipping. - New event types on webhooks. Subscribe to the specific events you need, and ignore others.
- New error
codevalues. Fall back to the HTTP status.
// Tolerant parsing: pick what you need, ignore the rest.
const { id, attributes } = body.data
const conversation = {
id,
name: attributes.name ?? '',
status: ['open', 'snoozed', 'done'].includes(attributes.status) ? attributes.status : 'unknown',
}Deprecation
Deprecated operations are labeled Deprecated in the API reference. They keep working, but new integrations shouldn't use them. Check the operation's description for the recommended alternative.
Changes and deprecations are announced in the changelog, which you can also read as Markdown.