API versioning & breaking changes

Moov releases a new API version each quarter. Pin every request to a version so changes reach your integration only when you choose to upgrade.

Set the version header

Send the X-Moov-Version header with every request, set to a version such as v2026.07.00. Without the header, Moov uses the oldest supported version, v2024.01.00. See the version reference for every version and what changed.

curl -X GET "https://api.moov.io/accounts/{accountID}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

How API versions work

API versions use the format vYYYY.QQ.BB:

Part Meaning
YYYY The year
QQ The two-digit month that starts the quarter: 01, 04, 07, or 10
BB The build number, starting at 00, for later builds in the same quarter

For example, v2026.01.00 is the API version for Q1 2026.

Each quarter's version is published one quarter early with an in development status. Breaking changes can land in an in development version without notice, so use it with caution. On the first day of its quarter, the version is officially released, and no breaking changes are added to it after that. The next quarter's version then becomes the new in development version.

For example, v2027.01.00 is published as in development on October 1, 2026. On January 1, 2027, v2027.01.00 is released and v2027.04.00 is published as in development.

How Moov announces breaking changes

Moov can change the API at any time. Moov communicates breaking changes to you directly, with enough time to update your integration, and announces them in the changelog (subscribe for notifications). Moov may also update its SDKs with any of the breaking changes below; SDK fixes can result in changes to the API.

In the tables below, "field" means a field in a request or response body, a query parameter, a header value, or any other value the API uses.

Breaking changes

These changes require you to update your integration.

Change Example Impact on your integration
Removing a field Removing lastName from the user profile response Code that depends on the field gets errors or incomplete data
Changing a field's data type Changing id from a string to an integer Code expecting a string may fail to parse the integer
Changing the response structure Changing a flat JSON response to nested JSON Parsing based on the old structure must change
Removing an endpoint Removing GET /users/{userID}/profile Calls to the endpoint stop working
Changing an endpoint URL Moving /user to /profile/user Calls fail until they use the new URL
Changing required request fields Making email required where it was optional, or adding a new required field Requests fail if the field isn't provided
Changing an HTTP method Changing POST to PUT to create a resource Requests must use the new method
Changing a default value Changing the default sortOrder from ASC to DESC Code that relied on the old default must adapt; otherwise it can be ignored
Changing a date format Changing MM-DD-YYYY to YYYY-MM-DD Date parsing must adapt
Adding authentication requirements Requiring an API key on an endpoint that didn't need one You must add the new authentication
Renaming a field Renaming username to user_name References must use the new name
Changing pagination logic Switching from page-based to cursor-based pagination Pagination handling must change
Changing a field's valid values Removing a previously valid enum value Requests must use a different value
Adding a response field that requires action Adding a disabledOn timestamp that marks the resource as disabled and non-interactable New fields are usually non-breaking, but this one changes how you can use the resource
Adding an enum value that Moov sets and you read Adding DISABLED to an existing status enum Code that doesn't handle the new value may fall through to a catch-all error
Changing a specific status code in a bug fix Changing 404 Not Found to 409 Conflict Code that expects 404 for that case must handle 409

Non-breaking changes

These changes don't require updates, as long as your integration follows common API client practices, such as ignoring unknown response fields.

Change Example Why it's non-breaking
Adding an optional response field Adding an optional middleName to the user profile response Unaffected, unless you strictly validate response fields
Adding an informational response field Adding a createdAt or updatedOn timestamp that's always returned Unaffected, unless you strictly validate response fields
Adding an endpoint Adding GET /users/{userID}/friends Existing calls don't change
Deprecating an endpoint with adequate notice Marking GET /users/{userID}/profile deprecated while it still works The endpoint keeps working while you update
Improving performance or fixing non-behavioral bugs Faster responses, or fixing a documentation typo The interface and behavior don't change
Adding a response header Adding X-Request-ID to responses Existing headers don't change
Adding an enum value that you set and Moov reads Adding NEW_FEATURE to an existing action enum You only receive values you sent
Fixing an error response Changing 500 Internal Server Error to 409 Conflict A 500 is never a valid response from a working API, so replacing it with a defined error code is a fix, not a breaking change
Ordering arrays consistently when no order is specified Returning ['b', 'a'] without an ordering query argument Array items don't depend on order
Ordering maps consistently Returning {"b": true, "a": true} Values are looked up by key

Next steps