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 `.`. Old keys of the format `` or `` 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. You do not need to upgrade your API version to create or start using a new-format key. However, this API version requires the new key format, so replace any old-format keys before upgrading. ## 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" } }` If you are not using the `welcome` parameter, no change is needed. ## 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. Previously, `from` and `to` lived alongside the other top-level attributes. They now live within `options`. ## Export orders with no reports no longer return error code 422

(Changed)

Previously, a `POST` that created an export order containing no reports failed with status code 422, and no export order was created. The `POST` now succeeds and creates the export order. After it has been processed, retrieving the export order will show a `state` of `failed` and an `error_message` explaining that no output was available. ## 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. Before: `{ "error_messages": ["No file output available"] }` After: `{ "error_message": "No file output available" }` ## 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. Companies that do not use the branches functionality do not need to specify a branch. ## 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. The following role names have also 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