This article provides information on leveraging manual API calls to update user provisioning. Please reach out to your Workvivo Technical contact to alert them that you are going to provision your users this way, as we will need to update a few items on our side first.
Please find our sample POST, PUT, and PATCH examples below to reference. Also, attached is a sample json collection for reference.
If you let us know what employee data points you would like to have on each employee profile (i.e. additional team types of custom fields), we can get that up for you on our side and provide more details on the specific attribute calls if you'd like.
Notes:
- Please ensure ExternalID is unique per user and does not change.
- Additionally, please do not pass NULL values to Workvivo. Instead, please use empty strings or remove operation.
Sample SCIM POST request:
Request URL: https://[company domain]/scim/v2/scim/Users/
example: https://company.workvivo.com/scim/v2/scim/Users/
Request Method: POST (create)
Sample request:
{
"emails": [
{
"type": "work",
"value": "Joe.Bloggs@example.com",
"primary": true
}
],
"displayName": "Joe Bloggs",
"addresses": [
{
"locality": "Ireland",
"type": "work"
}
],
"displayName": "Joe Bloggs",
"meta": {
"resourceType": "User"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"name": {
"formatted": "Joe Bloggs",
"familyName": "Bloggs",
"givenName": "Joe"
},
"externalId": "JBloggs",
"active": true,
"authRoles": ["admin", "moderator"],
"authMode": "password"
"userName": "Joe.Bloggs@example.com",
"title": "QA Tester",
"phoneNumbers":
[
{ "primary": true, "type": "work", "value": "+1 123 12345" },
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "department term 1",
"costCenter": "costCenter term 1",
"manager": {
"displayName": "Mary Berry",
"value": "343826",
"$ref": "https://company.workvivo.com/scim/v2/scim/Users/343826"
},
"taxonomies": [
{
"displayName": "Team Term",
"type": "Team Label"
},
{
"displayName": "Northeast",
"type": "Region"
}
]
}
}
Sample SCIM PUT request:
Request URL: https://[customer domain]/scim/v2/scim/Users/662096
example: https://company.workvivo.com/scim/v2/scim/Users/662096
Request Method: PUT (create or update)
Sample request:
{
"emails": [
{
"type": "work",
"value": "Joe.Bloggs@example.com",
"primary": true
}
],
"displayName": "Joe Bloggs",
"addresses": [
{
"locality": "Ireland",
"type": "work"
}
],
"displayName": "Joe Bloggs",
"meta": {
"resourceType": "User"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"name": {
"formatted": "Joe Bloggs",
"familyName": "Bloggs",
"givenName": "Joe"
},
"externalId": "JBloggs",
"active": true,
"id": "662096",
"userName": "Joe.Bloggs@example.com",
"title": "QA Tester",
"phoneNumbers":
[
{ "primary": true, "type": "work", "value": "+1 123 12345" },
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "department term 1",
"costCenter": "costCenter term 1",
"manager": {
"displayName": "Mary Berry",
"value": "343826",
"$ref": "https://company.workvivo.com/scim/v2/scim/Users/343826"
},
"taxonomies": [
{
"displayName": "Team Term",
"type": "Team Label"
},
{
"displayName": "Northeast",
"type": "Region"
}
]
}
}
Sample SCIM PATCH request:
Request URL: https://[customer domain]/scim/v2/scim/Users/662096
example: https://company.workvivo.com/scim/v2/scim/Users/662096
Request Method: Patch (update)
Sample request:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[
{
"op": "Replace",
"path": "active",
"value": "False" // Deactivate user = set to False
},
{
"op": "Replace",
"path": "title", // Job Title
"value": "Plant QA"
{
"op": "Replace",
"path": "mobilePhoneNumber", // Mobile Number
"value": null
},
{
"op": "Replace",
"path": "workPhoneNumber",
"value": "+66 61 6"// Direct Dial
},
{
"op": "Replace",
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department", // Primary Team Type
"value": "IT"
},
{
"op": "Replace",
"path": "addresses[type eq \"work\"].locality", // Secondary Team Type
"value": "Paris"
},
],
}
Default Attributes and Mappings to Workvivo:
Please see below for specific term mappings. Please don't hesitate to reach out to your Workvivo contact for example call requests on the below, if needed
- ExternalID: Unique identifier provided per user that will anchor user information. This will dictate any changes on the user profile
- Username and Email: Email field in Workvivo
- FirstName: First Name/Given Name
- LastName: Last Name/Surname
- Active: Whether the user's account should be active or deactivated
- DisplayName: Display Name
- DirectDial: Direct (Work) phone number
- MobilePhone: Mobile phone number
- DateOfBirth: Date of Birth
- HireDate: Hire Date
- JobTitle: User's Job Title
-
Manager: User's Manager that generates org chart
- Please note, this must be in Email format or WorkvivoID
- Please note, this must be in Email format or WorkvivoID
Additional team types:
Please connect with your Workvivo contact to add or adjust team types in Workvivo
- Department: Default team type, which related to the primary structure setting
- Locality: Default team type, which related to the primary secondary setting
- CostCenter: Tertiary structure setting
To learn more about our team types and structure settings, please visit our help center article here