Use API provisioning to update members, teams, and reporting structures in Workleap through a single, secure process. The API pushes CSV files from your HRIS through HTTPS to automate recurring org-wide syncs with Workleap.

Preface

This integration requires API-related software development skills.
To set up an integration, you must be a Workleap Administrator.
To pull Officevibe engagement or feedback data, visit api.officevibe.com.
Do you already have a custom integration with our legacy API? See how to update your script files here.

Step 1: Enable API provisioning

Go to Settings > Provisioning.
Select Connect next to API Provisioning.
Create an organization management API Key if one doesn’t exist.
- You can do this from Settings > API or the API provisioning screen.
Set a risk threshold to avoid unwanted changes from poorly formatted CSV files.
Use the toggle to enable or disable Automatic Invite to auto-invite new users.
Select Activate integration.
- Only one provisioning method can be active at a time.

Note: You can configure API Provisioning without activating it. If deactivated, sync API calls will fail.

Step 2: Set up your environment

Use a Windows environment with PowerShell to access api.workleap.com on port 443.
Download and extract provisioning.zip to a folder (e.g., C:\Workleap_Sync).
File contents:
- api-provisioning-script.ps1
- SampleData/ (with sample CSVs)
- Modules/ (PowerShell SDK files)
- README.txt

Step 3: Prepare the PowerShell script

Run api-provisioning-script.ps1 with the following required parameters:

apiKey — the API key from step 1.
membersCsvPath — path to members.csv.
teamsCsvPath — path to teams.csv.
teamsMappingsCsvPath — path to teams-mappings.csv.

Step 4: Prepare the CSV files

Prepare the CSV files to manage and update users, teams, and reporting structures in your organization. Each time the API syncs, Workleap uses these CSVs to reflect your current organizational structure. Be sure to adjust the file data as intended to avoid unexpected changes to your Workleap organization.

Note: Use UTF-8 encoded CSV files with comma delimiters and double-quote escaping.

Tip: Reference the samples in the SampleData folder (downloaded in step 2) for all 3 of the file types outlined below.

`members.csv`

Contains member data.
Identifies users by externalMemberId.
- Uses email as a fallback identifier if the externalMemberId doesn't match any member in your Workleap org.
To add a member:
- Add a row and enter their data.
To remove a member:
- Delete their row.
Optional fields and values:
- languagePreferences:
  - en
  - fr
- productAssignations:
  - Officevibe
  - Skills
  - LMS
  - Pingboard
  - Onboarding
  - Performance
  - Workleap AI
- Custom properties:
  - Use exact property names as configured in Workleap.

`teams.csv`

Creates teams based on the externalTeamId and teamName values.
Include all hierarchy levels (e.g., brands, business units, departments, subteams, etc., if applicable).
Include both direct reports and full hierarchies.
- E.g.,:
  - Smaller teams led by one Direct Manager.
  - Larger teams made up of multiple subteams.

`teams-mappings.csv`

Assigns members and managers to teams.
To assign members:
- Map externalTeamId (from teams.csv) to externalMemberId (from members.csv).
To create subteam structures (i.e., teams with subteams):
- Map externalSubteamId to externalTeamId (from teams.csv).
Build from the bottom up (subteams first).
Managers automatically gain access to their subteams.
- If there are multiple managers in a structure, upper managers can see data from the whole reporting line they manage (i.e., the employees of managers that they manage).

Tip: Use generic values for externalTeamId instead of manager names to reduce disruption if managers change.

Step 5: Run the script

When you run the script, each sync replaces the previous one.

Caution: Always include all 3 CSV files. Otherwise, the operation will fail.

Effects of missing data

The following happens when a member or team from the previous sync is no longer in the CSV files when the script is run:

Members missing from members.csv:
- If previously active — the missing members are deactivated.
- If previously invited/created — the missing members are deleted.
  - Exception — Admins are never auto-deleted or deactivated.
Teams missing from teams.csv:
- Previously active teams are deleted.

Run manually

To run the script and perform a sync manually:

Open PowerShell in your script folder.
Use the following sample command:

./api-provisioning-script.ps1 -apiKey "{apiKey}" ` -membersCsvPath "./SampleData/members.csv" ` -teamsCsvPath "./SampleData/teams.csv" ` -teamsMappingsCsvPath "./SampleData/teams-mappings.csv" ` -Verbose