13 new changes introduced in version 2025-12-01.

Summary

• Use PATCH instead of PUT for updating users and custom field options
• Require API keys to include both identifier and prefix
• Only accept bearer token as authentication method
• Remove duplicate data keys nested in data array
• Only accept application/json media type
• Move welcome and welcome_locale to meta field for user creation
• Move from/to fields to options.start_time/options.stop_time for export orders
• Export orders with no reports no longer return error code 422
• Replace error_messages field with error_message for export orders
• Remove deprecation warning about country and currency relationships
• Require specifying branch when creating user for companies using branches
• Remove deprecated reference field, replaced by external_identifier in users endpoint
• Replace role field with roles and role_branches in users endpoint

Use PATCH instead of PUT for updating users and custom field options

(Changed)

Updating a user or a custom field option is now performed with the PATCH http method, which means that only the fields you want to change are required to be part of the request payload.

Trying to use PUT will return a 405 Method Not Allowed error.

Require API keys to include both identifier and prefix

(Changed)

We have updated our API key schema to a newer version, with an identifier along with a prefix to help identify tokens better (used to provide better error messages if the wrong token is used).

New API keys follow the format <identifier>.<prefix><secret>. Old keys of the format <prefix><secret> or <secret> will no longer be accepted for authentication. A new API key will look something like this:

s6v8hvk6uw6wwa1a1hm7ak3j.skvk_api_MbL5wM0cymk62SutZMYtT5paKrijm20Z2g50

If you are using an API key using the old format (any key created before 2025-09-08), create a new key and remove the old one.

Only accept bearer token as authentication method

(Changed)

All API requests now only accept authentication by bearer token, removing the possibility to use basic http authentication.

Remove duplicate data keys nested in data array

(Changed)

All GET requests to index endpoints returning an array of resources will now only have one level of data, the top level one.

For example, the response of a GET request to the users endpoint previously looked like this:

{ "data": [ { "data": { ... } }, { "data": { ... } } ] }

but will now be in this format instead:

{ "data": [ { ... }, { ... } ] }

Only accept application/json media type

(Changed)

All endpoints will now return error if application/json is not accepted by the request (specified by the Accepted header).

Additionally, POST, PUT, and PATCH requests are now required to specify the Content-Type header as application/json.

Move welcome and welcome_locale to meta field for user creation

(Changed)

When creating a user, the previous query parameters welcome and welcome_locale will now have to be supplied in the meta field in the request body.

For example, what was previously /v1/users?welcome=yes&welcome_locale=en would now be supplied as:

{ "data": { ... }, "meta": { "welcome": "yes", "welcome_locale": "en" } }

Move from/to fields to options.start_time/options.stop_time for export orders

(Changed)

The fields from and to have been moved to the options hash and been renamed to start_time and stop_time respectively.

Export orders with no reports no longer return error code 422

(Changed)

When creating an export order that contains no reports, the request will now be successful and return the export order containing an error message pertaining to this.

Replace error_messages field with error_message for export orders

(Changed)

The new field error_message holds a single error message instead of an array of error messages.

Remove deprecation warning about country and currency relationships

(Removed)

Removed the deprecation warning about the support ending for the relationships country and currency when listing branches.

These are now only represented by the country_code and currency_code attributes.

Require specifying branch when creating user for companies using branches

(Changed)

When creating a user, companies that use branches now have to specify which branch the user should belong to.

The endpoint will return error code 400 otherwise.

Remove deprecated reference field, replaced by external_identifier in users endpoint

(Removed)

The users endpoint no longer accepts the previously deprecated reference field, which has been replaced by external_identifier. Relevant when creating, updating or listing users.

Replace role field with roles and role_branches in users endpoint

(Changed)

Replaces the user role field with the new roles field and role_branches relationship.

This allows specifying multiple roles scoped to specific branches when creating or updating a user. Additionally, listing a user now shows all their roles and branch scopes.

Some of the old role names have also been changed:

• user_management => employee_manager
• export_only => exporter

Additionally, the regular role is now the default and should not be specified.