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

Note: Workleap API provisioning supports CSV and JSON configurations. This article describes JSON-based user provisioning setups. For CSV setups, click here.

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 payload here.

Important: When setting up an API provisioning or HRIS integration for the first time, make sure that the email address of any user who was manually added to Workleap matches their email address in your provisioning source.

During the initial sync, Workleap cannot update existing users' email addresses.
After the initial sync, user email addresses will be kept up to date automatically with each daily sync.

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 when a sync exceeds your chosen limit.
Use the toggle to enable or disable Automatic Invite, which sends a Workleap invitation to newly created 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: Authentication

Always include a workleap-subscription-key header followed by your API key. Your API key is generated in the provisioning configuration page of your Workleap Settings.

Example

workleap-subscription-key: <your-api-key>

Step 3: Prepare the JSON payload

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

Payload breakdown

`members`

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.
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`

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`

Assigns members and managers to teams.
To assign members:
- Map externalTeamId (from teams) to externalMemberId (from members).
To create subteam structures (i.e., teams with subteams):
- Map externalSubteamId to externalTeamId (from teams.json).
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).

Note: All fields are case-sensitive. If applicable, you can include additional fields (i.e., custom attributes).

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

Example payload

{
  "members": [
    {
      "externalMemberId": "EMP001",
      "email": "foo@workleap.com",
      "firstName": "Foo",
      "lastName": "Bar",
      "jobTitle": "Engineer",
      "imageUrl": "https://...",
      "languagePreferences": ["en", "fr"],
      "productAssignations": ["Officevibe", "Skills"],
      "Extra Custom Propery": ""
    }
  ],
  "teams": [
    {
      "externalTeamId": "TEAM001",
      "teamName": "Operations"
    }
  ],
  "teamMappings": [
    {
      "externalTeamId": "TEAM001",
      "externalMemberId": "EMP001",
      "isMember": true,
      "isManager": false
    }
  ]
}

Step 4: Send a POST request to the endpoint

API Endpoint

PUT https://api.platform.workleap.com/public/provisioning/json/process-and-schedule

The API validates your payload and schedules the provisioning process. Each sync replaces the previous one.

Caution: Always include all 3 payload sections. Otherwise, the operation will fail.

Curl example

curl -X PUT \
  'https://api.platform.workleap.com/public/provisioning/json/process-and-schedule' \
  -H 'Content-Type: application/json' \
  -H 'workleap-subscription-key: <your-api-key>' \
  -d @your_payload.json

Effects of missing data

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

Members missing from members:
- 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:
- Previously active teams are deleted.

View sync history

To view the history of all your provisioning syncs:

Go to Settings > Provisioning, then click View sync history.
Review the list of sync jobs with their status and source.

Note: Provisioning syncs from the API always have API Provisioning as their source value.

Sync statuses

Syncs on the view sync history page show one of the following statuses:

Pending — Sync is running.
Paused — Risk threshold exceeded. Approve or reject changes.
Rejected — Paused sync was rejected.
Success — Sync completed (may have been previously Paused).
Warning — Partial success; check report for issues like duplicates.
Failed — Sync didn’t run.

Need more help?

Read our API Provisioning FAQ for troubleshooting tips and advanced use cases.
For all supported fields and error codes and other additional API info., refer to our Workleap Developer Portal.
Contact our support team via the chatbot widget for personalized assistance.

API Provisioning FAQ

Slack Integration

API Provisioning (CSV)

Update a legacy provisioning script for API provisioning (CSV)

Update a legacy provisioning payload for API provisioning (JSON)

API Provisioning (JSON)