Synchronization of user data with an external HR system – FireServiceRota

Purpose

It is possible to create and update users through our API, for example to keep information in sync with an external HR system. We currently support management of the following elements through the API:

Creating and updating users.
Assigning a Rank to a user.
Manage Memberships of the user in different groups (stations, teams, etc.):
- Make the user a member of a station
- Suspend a user's membership (by setting an end_time)
Add or change Skills at specific stations for specific periods of time.
Add or change Positions at specific stations for specific periods of time.
Add or change Contracts for the user in general.

Prerequisites

There are a few prerequisites to get access to this functionality.

To fully meet the requisites, please contact our support team, and we will set up the configuration for you.

You must have an API User set up for the Region you want to manage. This functionality is not available for normal users connected to the API.
A Third Party Integration must be configured for the Region you want to manage. You will need the ID of the Third Party Integration of your Region to make use of the API endpoints you need.
The API User needs to be whitelisted for HR management in the Third Party Integration settings.
A foreign key identifier needs to be set up in the Third Party Integration settings. This can be the email of a user, or a personnel number.

Usage

Once everything is set up, and you've obtained an OAuth token, you will be able to make use of the following API endpoints:

GET on '/api/v2/third_party_integrations/{third_party_integration_id}/users/{user_foreign_key}'
This endpoint allows you to retrieve a user's information in JSON format. The structure of this JSON file is important, as it is the full JSON structure we support for performing any updates.
POST on '/api/v2/third_party_integrations/{third_party_integration_id}/users/'
This endpoint allows you to update every support aspect of a user: their memberships, contracts, positions and more. This endpoint only supports a specific JSON structure as payload. This JSON structure can be retrieved using the previous endpoint.

See the API documentation, section third_party_integrations for more details.

Important notes:

The foreign_key attribute must always be present in the request JSON.
Any omitted field will not be updated.
For array fields (contracts, positions, memberships), if you do not wish to update them, omit the field entirely. If you supply an empty array, in some cases (like with contracts) all contracts of the user will be removed.
IDs for skills, groups, ranks, etc can be retrieved from their respective endpoints. See the API documentation. You must ensure that all the IDs you supply for skills, groups, ranks and contracts are accessible by the API user.
The API is idempotent, meaning that it can be called multiple times with the same data without changing the result.
It is strongly advised to use the ISO8601 standard to encode dates and times.

Examples

Foreign key used in the examples below: personnel_number.

GET /api/v2/third_party_integrations/X/users/12345

Retrieve user with personnel number 12345, who has an active membership in group ID 150 with a currently active skill with ID 157.

Response

{
  "memberships": [
    {
      "active_periods": [
        {
          "start_time": "2021-01-01T00:00:00.000+01:00",
          "plannable": true
        }
      ],
      "certifications": [
        {
          "start_time": "2021-01-01T00:00:00.000+01:00",
          "skill_id": 157
        }
      ],
      "positions": [

      ],
      "group_id": 150
    }
  ],
  "phone_numbers": [

  ],
  "contracts": [

  ],
  "id": 138,
  "first_name": "Keenan",
  "last_name": "Nielsen",
  "nickname": "KNielsen",
  "enlisted_at": "2021-01-01",
  "personnel_number": "12345",
  "email": "info@example.com"
}

POST /api/v2/third_party_integrations/X/users/

Set an end time on the membership of user with personnel_number 12345. This effectively terminates the user's membership in group 153 at that date.

Request

{
  "personnel_number": "12345",
  "enlisted_at": "2021-02-14",
  "memberships": [
    {
      "group_id": 150,
      "active_periods": [
        {
          "start_time": "2021-01-01",
          "end_time": "2021-06-30",
          "plannable": true
        }
      ]
    }
  ]
}