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.

Changelog

Version 2025-12-01