Breaking Changes

What's a Breaking Change?

An API is a contract between a provider and a consumer. Our commitment is to maintain this contract's stability. A breaking change is a modification that is not backward-compatible, altering this contract in a way that would cause a compliant, correctly implemented client to fail.

It's important to understand that according to industry standards for API versioning and backward compatibility, we do not consider the addition of new, optional fields or resources a breaking change. We encourage our clients to build resilient integrations that can gracefully handle new, unrecognized fields without failing. This approach ensures your systems can adapt to our API enhancements without constant updates.

Breaking Changes: Action Required 🚨

The following changes will always be considered breaking changes:

Endpoint Changes: This includes removing an endpoint, changing the HTTP method (like from GET to POST), altering the URL path structure (e.g., /candidates/{id}to /applicants/{id}), or changing the functionality of an endpoint (e.g., a search endpoint now needing authentication).
Request Parameter Changes: This happens when required parameters are removed or optional ones become required. It also includes changing parameter names or data types (like string to integer), modifying validation rules (e.g., reducing max length), or changing a parameter's location (e.g., from a query parameter to the request body).
Response Structure Changes: This involves removing fields from a response, changing field names (e.g., firstName to first_name), or modifying data types (e.g., string to object). It also covers changes to field formats (like date format) and restructuring nested objects or arrays.
Authentication & Authorization Changes: Changes to authentication methods (e.g., from API key to OAuth 2.0), modifying required scopes for existing endpoints, or deprecating access methods entirely are considered breaking changes. Changing token formats or validation requirements also falls into this category. Note: When new authentication methods like OAuth 2.0 are introduced for existing endpoints that currently use API keys, we will support both methods during a transitional period. However, the eventual deprecation and removal of API key support will be considered a breaking change and will be announced in advance with a clear sunset date.
Status Code & Error Changes: This includes altering HTTP status codes for existing scenarios (e.g., 200 to 201), modifying the structure of error responses, or changing error codes and their meanings. Removing error codes that clients might rely on is also a breaking change.
Behavioral Changes: Altering default values for parameters or responses, changing pagination behavior, and applying stricter data validation rules that reject previously valid data are considered breaking changes. Note, while changes like modifying rate limits (reducing limits significantly) might also be considered as behavioral breaking changes, we would typically communicate these upfront rather than introduce a new API version.

Non-Breaking Changes: Safe Updates ✅

The following changes are backward-compatible and do not require a new API version:

Additive Changes: This includes adding new optional parameters to requests, adding new fields to responses, adding new endpoints or resources, introducing new HTTP methods for existing resources (without removing old ones), or adding new enum values.
Enhancements: Improvements to error messages (without changing codes or structure), adding new optional headers, expanding field descriptions in documentation, performance improvements that don't change behavior, and bug fixes that restore documented behavior are all non-breaking changes.
Relaxations: Making required parameters optional, relaxing validation rules (e.g., allowing longer strings), increasing rate limits, or extending timeout values are also considered safe updates.

Our API Evolution

We follow these principles for our API evolution:

Deprecation: We provide a minimum of 10 months' notice before an endpoint is sunset, along with a clear migration path. We use multiple channels to communicate these changes, including changelogs, email, and documentation.
Backward Compatibility: We support previous API versions for at least 24 months after communication. Additive changes are rolled out to all supported versions when possible, while breaking changes require a new API version with proper migration guides.

Best Practices for Our APIs

For each new API version, we recommend:

Review the changelog for your current API version.
Identify any breaking changes that affect your integration.
Plan your migration timeline to stay within the supported window.
Update the API version headers in your requests.
Pin your integrations to a specific API version instead of using "latest" to avoid unexpected issues.
Monitor for deprecation notices.
Implement graceful handling for new optional fields.

We also send email notifications and update our documentation and changelogwith each release