If you previously used a custom API integration for user provisioning, you need to update your JSON payload to align with the updated API provisioning format. This update ensures that your API provisioning syncs remain successful and that new users and teams are updated as expected.
Note: Workleap API provisioning supports CSV and JSON configurations. This article describes JSON-based user provisioning setups. For CSV setups, click here.
Note: The API remains backward compatible with legacy API payload (except for the settings parameter). However, updating is simple and quick and ensures you have access to new features.
Update your legacy API payload for API provisioning
Use the tables below to convert your existing payload and fields to the current API provisioning format:
users
Legacy Section | New Section |
|
|
Legacy Field | New Field | Notes |
id | externalMemberId | Required |
language | languagePreferences | Use language codes (e.g., fr, en) |
| productAssignations | New field; defaults to Officevibe if no product is specified |
Note: Copy over all custom fields as they are.
groups
Legacy Section | New Section |
|
|
Legacy Field | New Field |
id | externalTeamId |
name | teamName |
mappings
Legacy Section | New Section |
mappings | teamMappings |
Legacy Field | New Field |
groupId | externalTeamId |
userId | externalMemberId |
subGroupId | externalSubteamId |
isMember | isMember (unchanged) |
isManager | isManager (unchanged) |
About the settings section
In the legacy API, the settings section controlled:
Admin user syncs (
syncAdmin)Whether or not new users are invited (
inviteNewUsers)
In the current API:
There's no need to include syncAdmin in the payload (your admin context comes from the API key, and invitation settings are managed on the Provisioning page of Workleap Settings).
Important: If your payload includes the settings section, you'll get an error response.
Payload examples
Legacy format
Legacy format
{
"settings": {
"syncAdmin": "00000000-0000-0000-0000-000000000000",
"inviteNewUsers": false
},
"users": [
{
"externalMemberId": "SOME-EXTERNAL-ID",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"jobTitle": "Some job title",
"imageUrl": "",
"language": "English",
"Extra Custom Property": "Some custom value"
}
],
"groups": [
{
"id": "SOME-EXTERNAL-TEAM-ID-1",
"name": "Some Parent Team"
},
{
"id": "SOME-EXTERNAL-TEAM-ID-2",
"name": "Some Team"
}
],
"mappings": [
{
"groupId": "SOME-EXTERNAL-TEAM-ID-1",
"userId": "SOME-EXTERNAL-ID",
"subGroupId": null,
"isMember": false,
"isManager": true
},
{
"groupId": "SOME-EXTERNAL-TEAM-ID-1",
"userId": null,
"subGroupId": "SOME-EXTERNAL-TEAM-ID-2",
"isMember": false,
"isManager": false
}
]
}
Current format
Current format
{
"members": [
{
"externalMemberId": "SOME-EXTERNAL-ID",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"jobTitle": "Some job title",
"imageUrl": "",
"languagePreferences": ["en"],
"productAssignations": ["Officevibe"],
"Extra Custom Property": "Some custom value"
}
],
"teams": [
{
"externalTeamId": "SOME-EXTERNAL-TEAM-ID-1",
"teamName": "Business"
},
{
"externalTeamId": "SOME-EXTERNAL-TEAM-ID-2",
"teamName": "Operations"
}
],
"teamMappings": [
{
"externalTeamId": "SOME-EXTERNAL-TEAM-ID-1",
"externalMemberId": "SOME-EXTERNAL-ID",
"externalSubteamId": null,
"isMember": false,
"isManager": true
},
{
"externalTeamId": "SOME-EXTERNAL-TEAM-ID-1",
"externalMemberId": null,
"externalSubteamId": "SOME-EXTERNAL-TEAM-ID-2",
"isMember": false,
"isManager": false
}
]
}
After you update your payload
Generate a new API key.
Set your risk thresholds.