User Sync

Keeping Flowcase users in sync with your HR system or identity provider ensures that people have access from day one, permissions stay correct, and leavers are deactivated promptly.

There are three supported approaches:

1. SCIM v2 (recommended): automatic provisioning from your identity provider. Works with Microsoft Entra/Azure AD, Okta and all main enterprise identity providers that support the SCIM standard.
2. Users API: build custom sync logic for anything SCIM does not cover.
3. CSV upload: send Flowcase updated user lists as CSV files and we work out which changes to make.

Read through all three before you decide how to synchronise your users with Flowcase.

SCIM v2 Provisioning

SCIM (System for Cross-domain Identity Management) is an open standard for automating user provisioning. Flowcase supports SCIM v2, allowing you to synchronise users directly from identity providers such as:

• Microsoft Entra / Azure AD
• Okta

With SCIM, your identity provider pushes changes to Flowcase automatically. When a user is created, updated, or deactivated in your directory, the change is reflected in Flowcase without any custom code.

SCIM also supports mapping roles and permissions, so you can control the level of access users have in Flowcase directly from your identity provider.

Getting started with SCIM

• See the SCIM API reference for the full specification.
• Follow the SCIM - Microsoft Entra guide for step-by-step setup instructions with Microsoft Entra / Azure AD.

What SCIM handles

• Creating users when they are assigned to the Flowcase application
• Updating user attributes (name, email, department, etc.)
• Deactivating users when they are unassigned or soft-deleted
• Assigning roles via App Roles in your identity provider

Users API

The Users API gives you full control over user lifecycle management via REST. Use it when you need to integrate with systems that do not support SCIM, or when you need fine-grained control that goes beyond what SCIM provides.

Lookup users

Search users

GET https://<subdomain>.flowcase.com/api/v2/users/search

Find user by ID

GET https://<subdomain>.flowcase.com/api/v1/users/<user_id>

Find user by email, external ID, or UPN

GET https://<subdomain>.flowcase.com/api/v1/users/find?email=<value>
GET https://<subdomain>.flowcase.com/api/v1/users/find?external_unique_id=<value>
GET https://<subdomain>.flowcase.com/api/v1/users/find?upn=<value>

Create a user

POST https://<subdomain>.flowcase.com/api/v1/users

{
  "user": {
    "country_id": "<country_id>",
    "email": "<email>",
    "upn": "<upn>",
    "external_unique_id": "<employee_id>",
    "office_id": "<office_id>",
    "role": "<role>",
    "extra_roles": [],
    "name": "<name>",
    "telephone": "<telephone>",
    "landline": "<landline>",
    "born_year": 1990,
    "title": { "no": "<title>", "int": "<title>" },
    "nationality": { "no": "<nationality>", "int": "<nationality>" },
    "ensure_unique_custom_tag_ids_by_category": {
      "<category_id>": "<tag_id>"
    },
    "send_email": false
  }
}

Set send_email to true to send a welcome email to the new user.

Update a user

PUT https://<subdomain>.flowcase.com/api/v1/users/<user_id>

Only include the fields you want to change. When changing office_id, you must also provide the country_id of the new office's country.

Deactivate a user

PUT https://<subdomain>.flowcase.com/api/v1/users/<user_id>

{
  "user": {
    "deactivated": true
  }
}

Reactivate a user

PUT https://<subdomain>.flowcase.com/api/v1/users/<user_id>

{
  "user": {
    "deactivated": false,
    "send_email": false
  }
}

Set send_email to true to send a welcome email on reactivation.

Delete a user

DELETE https://<subdomain>.flowcase.com/api/v1/users/<user_id>

Deleting a user permanently removes them from Flowcase. This cannot be easily undone.

CSV upload

Flowcase can ingest a CSV file listing your current users. You can upload the file to the user sync API, or to an SFTP folder we provide. Synchronisations of this kind usually run nightly, but the frequency is up to you.

When Flowcase processes the file we will:

• Create users that have a row in the file but are missing in Flowcase.
• Update any users that have changed (including changing department).
• Optionally remove or deactivate any users that are missing from the file.
• Notify a user via email whenever their email address has changed.

You should note that:

• Users are matched on external_unique_id first, falling back to the email field.
• External users are not deactivated even if they are not in the list.
• External users in the account are promoted to normal users if they are in the list, provided they match on external_unique_id or email and the default role is for a normal user.

If you are considering this option, please contact your Customer Success Manager.

CSV file fields

You can supply the following fields in the CSV file. If the file is exported from a user directory and you do not control the column headings, we can map those columns to ours. We need an example file in that case, so that we can set up the correct mappings in advance.

Roles in the CSV

Roles are assigned through the roles column (or a custom column you map roles to). The column takes a space-separated list, where the first value is the base role for the user, followed by any extra roles.

Format: base_role extra_role extra_role

Example:

...,email,roles,...
...,foo@bar.com,consultant countrymanager,...

This gives the user foo@bar.com the consultant base role and the countrymanager extra role.

Roles are a single list within the roles column, so you must enter a single base role along with any extra roles together. See User roles for what each base and extra role can do.

Additional fields for custom tags

As well as the fields listed above, you can provide extra columns that map to custom tags in Flowcase. If a user has a value for a custom tag specified in the CSV, that tag is applied during the import. Custom tags can carry things like extra department or hierarchical information, or show the user's line manager. See Custom tags, and ask your Customer Success Manager for more on setting up custom tags in Flowcase.

Things we need to know

Before you upload a CSV file, Flowcase needs to enable and configure this feature for your account. Once you have decided on the format of your CSV file, contact techsupport@flowcase.com or your Customer Success Manager to set things up for you.

Some things we need to know:

There are two ways to upload the CSV file to Flowcase: to our API, or to our SFTP server.

Upload via the API

You need an API key with administrator-level access. If you cannot create one yourself, ask someone with administrator access to Flowcase to create it for you. Include the key in the Authorization header of your HTTP requests. See Authentication & Security for the header format.

POST the file to:

POST https://<subdomain>.flowcase.com/api/v1/users/import/csv/<config_name>?dry_run=true

Parameters

Request body

• The body of the request should be the CSV file encoded with UTF-8.
• Set the Content-Type header to text/csv.
• When using curl to upload data to the API, use the --data-binary flag when pointing to a CSV file. Other data flags such as --data or -d can transform the payload unexpectedly (trimming line breaks, for example), while --data-binary performs no transformation.

Response

The API responds with HTTP 200 for success, and 4xx for input errors. A successful response means the file upload finished and synchronisation has started. The changes may not be visible straight after the upload, and can take some time before an end user sees them.

{
    "import_task": "85549c4c-31fb-44b4-bb70-da9wwc2b07a3",
    "dry_run": false
}

cURL example

curl --location 'https://<subdomain>.flowcase.com/api/v1/users/import/csv/default?dry_run=true' \
--header 'Content-Type: text/csv' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-binary '@/Users/john/flowcase/user_list.csv'

Upload via SFTP

You can upload the file to our SFTP server. The file is processed shortly after it is uploaded.

Filename

Include the date of the upload in the name of the file, for example users_20220922.csv, so that the various uploads are easy to tell apart over time.

Required details

To enable the SFTP user sync, Flowcase needs the following information:

SFTP server details

The connection should succeed, provided you connect from the IP ranges you gave us and use the same public key you provided. A 'connection timed out' error can mean you are connecting from an IP address we have not allowed.

User roles

Each user has exactly one base role and may also have additional extra roles.

Base roles

Extra roles

bidmanager is also accepted as an extra role. Its permissions are not documented here; ask your Customer Success Manager before assigning it.

When assigning the departmentmanager role, also include role_allowed_office_ids and/or role_allowed_tag_ids to specify which departments or tags the manager has access to.

Example: assign department manager role

PUT https://<subdomain>.flowcase.com/api/v1/users/<user_id>

{
  "user": {
    "role": "consultant",
    "extra_roles": ["departmentmanager"],
    "role_allowed_office_ids": ["<office_id_1>", "<office_id_2>"],
    "role_allowed_tag_ids": ["<tag_id_1>", "<tag_id_2>"]
  }
}

Custom tags

You can assign custom tags to users during creation or update using the ensure_unique_custom_tag_ids_by_category field. This sets one tag per category and removes any previous tag in that category.

To list available custom tag categories and tags:

GET https://<subdomain>.flowcase.com/api/v1/masterdata/custom_tags/custom_tag_category

See the Integrations API reference for full details.