Users API v2

The SameSystem Users API v2 allows you to manage employee records with more consistency, and an improved structure compared to previous version.
This API provides the essential tools to do user integrations securely and efficiently.

This version introduces new endpoints specifically for user handling. While department data is still retrieved via v1 endpoint, authorization is now also available through a dedicated v2 endpoint. Either v1 or v2 can be used to obtain an access token for performing requests. Only the user-specific data is versioned under /api/v2.

This approach ensures backward compatibility while enabling a gradual migration to the new structure.

Technical documentation for v2 can be found here.

Getting started

To get started, you must have a SameSystem user with correct permissions and with the necessary API access rights enabled by an administrator within the client. Once the setup is complete, you’ll receive API credentials that allow you to authenticate and interact with the system.
​

The first step will be familiarizing yourself with SameSystem’s API endpoints and the general integration flow. With the correct credentials, you’ll be able to:

All API requests return JSON responses and must include the following headers:

Content-Type: application/json

Authorization: Bearer <your-token>
​

Note: The Authorization header is required for all endpoints except login.

Authorization & department scope (via v1)

While the Users API itself lives under /api/v2, department scoping is still governed by the SameSystem API v1.
​

Authorization rules

To use SameSystem API, check the "Enable API" setting in the client's “General settings”, create a user through the UI, and enable the "API access" setting in the employee card, “Security” tab. Grant all necessary permissions for this particular user to accomplish given tasks. API permissions work precisely the same as permissions in web-based SameSystem. Attempting to access or modify users beyond your authorized permissions will not be successful.
​

Authorization (v1-based)

SameSystem uses OAuth 2.0 protocol for authorization, and it supports Resource Owner Password Credentials and Refresh token grant types.
Password grant type is used to get the access and refresh tokens. The access token is expiring in 1 hour, and the refresh token expires in 6 months. The tokens you'll receive are bearer. Every call you make will require you to have the access token in the Authorization header, so add Bearer and then the access token afterwards. You can get the access and refresh tokens with the API user and password received from SameSystem, and setting the grant_type to password. After the access token expires, you can use the Refresh token grant type to get a new access token.
To swap the refresh token for a new access token, use the same endpoint, but add this in the request body instead:
​

{ "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJpbmZvX2lkIjoiNWU2MDg5NTU3N2Y4OWNiNDg3N2EwMDE4IiwiZXhwIjoxNTk5Mjg1ODEwfQ.g74AIsgaXw0qHydop5X3FKJKGJMefcEnlJTAUD7B5jmNSKtf4sV6_wJQUwIXkrCYz9Xh0Pcvzj4nXWhJeTydnQ", "grant_type": "refresh_token" }
​

You can also look in the API v1 documentation here.

Alternatively, you can obtain the access token using the v2 endpoint. It works slightly differently, but both methods return a valid token that can be used to make requests.
​

What is {clientToken} in the URL and how to use it

Department identification

Departments can be referenced in user operations by internal SameSystem IDs and client-defined external identifiers.

Note: In v1, the equivalent of a client-defined external identifier was often called shop_custom_id. In v2, it’s the same field departmentId for both cases.

To use the external department ID simply ensure the value is provided in the department card and use the parameter: useExternalDepartmentId=true. This can be added in the URL like /api/v2/{clientToken}/users/create_with_contract?useExternalDepartmentId=true. This will map the provided departmentId with the according department that has the value set in the setup. Endpoints that support this feature specify it in the Parameters section of the swagger documentation.
​

You can retrieve department data using:

GET https://api.samesystem.com/api/v1/ctx_token/departments
​

This endpoint returns both internal and external identifiers so you can confidently reference departments when managing users.

User identification

Users can be referenced in operations by internal SameSystem IDs and client-defined external identifiers as well.

To use the external user IDs ensure the “Use custom IDs for employees” setting in the "General settings" is enabled and the value is provided in the employee card, “Security” tab or customID is present if users are created using the API. Use the parameter: useCustomId=true. This can be added in the URL like /api/v2/{clientToken}/users/{id}?useCustomId=true. This will map the id with the according user that has the custom ID value set. Endpoints that support this feature specify it in the Parameters section of the swagger documentation.

Custom fields

Custom fields can be referenced in operations by internal SameSystem IDs and client-defined external identifiers as well.

To use the external custom field IDs ensure the “Custom ID” field value is provided in the custom field setup. The body could look like this:

For internal SameSystem IDs the body could look like this:

It’s possible to send multiple values to a multiple choice field by providing an array like this:

Contract hours pr. weekday (hoursWeekWeekdays)
Allows you to define contract hours pr. weekday for an employee’s contract.
This feature is only applied if the following are enabled in the UI:

The value is a JSON-encoded string mapping weekday1 … weekday7 to decimal hour values.

Example:
"hoursWeekWeekdays": "{\"weekday1\":1.1, \"weekday2\":3, \"weekday3\":2, \"weekday4\":8.5, \"weekday5\":0, \"weekday6\":0, \"weekday7\":0}",
"workAmountType": "hours_per_weekday"

Fetching users (GET /api/v2/{clientToken}/users, GET /api/v2/{clientToken}/users/{id})

/api/v2/{clientToken}/users?fields[User]=email,fullName,contract.startDate,contract.status, customFields.extraField.id,customFields.extraField.name,customFields.value,contracts.department.id
​

Available values can be found in the swagger documentation

In v2 we no longer depend on defined templates done by SameSystem employees as we do in v1.

Note: we use titleId for providing a title on a contract for the user. You can retrieve title data using:

GET https://api.samesystem.com/api/v2/{clientToken}/titles

Creating a user (POST /api/v2/{clientToken}/users/create_with_contract, POST /api/v2/{clientToken}/users)

Updating a user (PUT /api/v2/{clientToken}/users/{id})

Note: a change of start date for employment will need to be done through PUT/api/v2/{clientToken}/users/{id}/update_start_date

Terminating a user (POST /api/v2/{clientToken}/users/{id}/terminate)

Rehiring a user (POST /api/v2/{clientToken}/contracts/rehire

Removing termination (POST /api/v2/{clientToken}/users/{id}/remove_termination)

Inserting a contract (POST /api/v2/{clientToken}/users/{userId}/contracts/insert)

Upserting users with contracts (POST/api/v2/{clientToken}/users/upsert_with_contracts)

A quick guide on how to use the API v2 Swagger documentation

1. Go to https://api.samesystem.com/api/v2.

2. Click on the required endpoint.

3. Select required fields to be returned in the response, if necessary, from the list.

4. Copy the request body example.

5. Click on "Schema" to view all available fields for the request body, along with their types, by expanding each value.