Breaking Change Policy

Learn about how we version our APIs to ensure your integration is robust.

Breaking Changes Policy

We aim to avoid releasing API changes that will cause any request that was previously successful to become unsuccessful or alter any response in a way that is likely to break a client implementation, except in the cases described below.

What changes do we consider non-breaking?

  • Add properties to a response
  • Add optional properties to a request
  • Add optional headers to a request
  • Add new endpoints
  • Add new request methods to existing endpoints
  • Add additional response headers
  • Support values in properties and headers that would previously have been rejected
  • Change the order of properties or array elements in a response, unless the order is explicitly specified
  • Change documentation
  • Make what would otherwise be a breaking change that is necessary to fix a security vulnerability
  • Change human-readable strings, such as title and detail in error messages
  • Change the format of future identifiers and other opaque strings, such as adding, removing, or altering prefixes (like prf_ for a profile resource) and changing the length of the string
  • Change an error’s HTTP status code or internal code to be more accurate or specific, such as changing a 400 to be a 404, etc.
  • Adjust response behavior based on preferences supplied in the Prefer header that were previously ignored.

What changes do we consider breaking?

  • Remove a property in a response
  • Restrict allowed properties in a request
  • Rename properties in a request or a response. For example: changing number to phone_number
  • Change a response to respond with an unexpected type. For example: returning null, where the type specification does not include null or returning String, where the type specification was Boolean
  • Change a response to have a value outside of a documented range or format. For example: returning 7275551234 where an E164 phone format was specified or returning a negative number in a field specified to be greater than 0
  • Remove a documented response header
  • Require an additional request header