SCIM - REST API Overview

You can call the Talentech SCIM API directly if you want to implement your own custom integration. This can be useful if you are not using Entra ID or your identity provider or identity management system does not support SCIM out of the box.

This page describes the best practices for the typical scenarios you need to implement when managing user accounts and permissions.

Data objects

The SCIM API operates on two main resources; Users and Groups. A user can be member of zero or more groups, but please note that you need each user to be member of at least one group in order to map it to a Talentech permission group.

Users

Holds the following core user data

• ExternalId - Customer owned user Id

• User name - An email is always expected

• Name - given name and family name in two separate properties

• Active - For a new user true is expected

The SCIM standard supports the definition of custom extensions. Talentech has implemented a unique SCIM extension for each of its product that needs it. These extensions are used to transmit product-specific data required to fully provision a user account within the respective product.

Example of product specific data:

• The user’s role in the product

• The organisation unit(s) the user belongs to

Note that it differs between between the products what data they require.

For a detailed specification of available SCIM extensions see the
API Documentation: POST Users
(Look for the Examples drop down where example payloads for each product can be viewed)

Groups

The group membership is used to grant access to different features withing the Talentech echo system. Examples are

• Access to a Talentech products like Webcruiter and Boarding

• Administrator access to user management

Note that detailed user permissions based on product-specific roles are often governed by each product's SCIM extension, rather than by group membership. However, group membership still governs access to the product itself.

Group mapping

Groups can be named however is most convenient for the customer.

The group name must be mapped to a Talentech group as part of the SCIM integration setup process. This mapping is handled by the Talentech implementation team.

How to get started

If you plan to create a customized integration with the Talentech SCIM API, you should contact the Talentech implementation team.

However, reading this documentation will help you get started and prepare for the integration process.

Preparation steps

1. Read documentation above
   It is important to understand the concepts explained above under Users and Groups.
   
   

2. Ensure you're familiar with the SCIM extension data that may be required to fully provision user accounts in your Talentech product(s). It's essential that your data source has access to all necessary user attributes invluding the extension data.
   
   

3. Agree on the group mapping
   This depends on which Talentech features/product your synced users will use. Discuss with implementation team.
   
   

4. Get an API Client
   Talentech implementation team will set one up for you.

Creating the technical integration

Below, you'll find an overview of common use cases and how to implement them. Be sure to read this in conjunction with the REST API documentation to get all the details you need

Create a group for users that should be provisioned to a specific Talentech feature/product

1. Create the group with your preferred name by calling endpoint POST /Groups
   
   

2. Ask Talentech implementation team to map group to the internal Talentech group representing the feature/product.
   
   
   

Provision a new user to a product that requires additional SCIM extension data

1. Send user including SCIM extension data by calling endpoint POST /Users
   
   

2. Optionally - store the identifier found in the response of the POST operation. It can be used for future operations on the user.
   
   

3. Add user to the product specific group by calling endpoint PATCH /Groups/{identifier} with the operation specifier "op": "Add"
   Example json for the patch requests can be found in API docs

Fetch a user

Option 1 - Using the Talentech SCIM identifier

1. GET /Users/{identifier}

Note that the identifier is the SCIM API specific identifier returned when a new user is posted

Option 2 - Using email

1. GET /Users/?filter=username+eq+{email}

In Talentech SCIM API username is always an email

Option 3 - Using externalId

1. GET /Users/?filter=externalId+eq+{externalid}

ExternalId is owned by integrating partner and can be any string

Note: Only users that has previously been created using the Talentech SCIM API can be fetched. Users that has been created further down the Talentech piepeline will not appear in the SCIM API. For example users created manually within a specific product or in Talentech user management will not show up in the SCIM API.

Deprovision a user that should no longer have access

Option 1 - When the Talentech identifier is available

1. Remove the user by calling DELETE /Users/{identifier}. Note that the identifier is the Talentech identifier (GUID). It was included in the respons when the user was created.
   
   

Option 2 - When the Talentech identifier is NOT available

1. Find the right user by calling endpoint with an additional filter parameter
   GET /Users/?filter=username+eq+{email}
   or

   GET /Users/?filter=externalId+eq+{externalid}
   
   The user returned will contain the Talentech identifier (GUID). In the payload the property is just named id
   
   

2. Remove the user by calling DELETE /Users/{identifier}. using the id from step 1 as identifier
   
   

Update product specific data by updating the SCIM extension

1. Fetch the user (see use case above) to get the Talentech SCIM Identifier
   
   

2. Call PATCH /Users/{identifier}
   Example json for the patch requests can be found in API docs