Direct SCIM API

This article provides information on leveraging manual API calls to update user provisioning. 

If you prefer to view a video walkthrough, you can skip ahead to this section.

To get started, an IT Administrator user in Workvivo can access the Provisioning Settings in the Admin Panel:

You will choose Other as the SCIM Provider and generate the SCIM secret token.

Additionally, there are a few other parameters you can alter:

• Allow Users to be reactivated from a POST call
• Allow Modifying Authentication Roles on SCIM PUT - we recommend enabling this if user roles are being managed via SCIM calls. If being managed in the admin panel, leave this setting to 'No'
• Allow Updating User authMode - we recommend enabling this if provisioning is set to a hybrid approach (users in Workvivo logging in via SSO and Password)

Please find our sample POST, PUT, and PATCH examples below to reference. Also, attached is a sample json collection for reference.

If you let your Workvivo contact (Onboarding PM before launch or our Support Team via 'Submit a request' post launch) 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:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "externalId": "8715", // Unique Identifier 
    "userName": "joe.bloggs@workvivo.com",
    "displayName": "Joe Bloggs",
    "name": {
        "formatted": "Joe Bloggs",
        "familyName": "Bloggs",
        "givenName": "Joe"
    },
    "emails": [
        {
            "type": "work",
            "value": "joe.bloggs@workvivo.com",
            "primary": true
        }
    ],
    "phoneNumbers": [
        {
            "primary": true,
            "type": "work",
            "value": "1234567"
        },
        {
            "primary": true,
            "type": "mobile",
            "value": "+1234567"
        }
    ],
    "addresses": [
        {
            "locality": "Ireland", // Secondary Team
            "type": "work"
        }
    ],
    "title": "Technical Support",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Customer Support", // Primary Team
        "costCenter": "Operations", // Tertiary Team
        "manager": {
            "displayName": "",
            "value": "654321",
            "$ref": ""
        },
        "taxonomies": [ // Additional Teams
            {
                "displayName": "Customer Experience",
                "type": "Division"
            },
            {
                "displayName": "Workvivo",
                "type": "Company"
            }
        ]
    }
}

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:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "externalId": "8751", // Unique Identifier 
    "userName": "Joe.bloggs2@workvivo.com",
    "name": {
        "formatted": "Joe Bloggs",
        "familyName": "Bloggs",
        "givenName": "Joe"
    },
    "emails": [
        {
            "type": "work",
            "value": "Joe.bloggs2@workvivo.com",
            "primary": true
        }
    ],
    "phoneNumbers": [
        {
            "primary": true,
            "type": "work",
            "value": "3534353"
        },
        {
            "primary": true,
            "type": "mobile",
            "value": "+354769999"
        }
    ],
    "addresses": [
        {
            "locality": "Location Name", // Secondary Team
            "type": "work"
        }
    ],
    "title": "Job Title",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Department", // Primary Team
        "costCenter": "Operations", // Tertiary Team
        "manager": {
            "displayName": "",
            "value": "654321", // Workvivo ID
            "$ref": ""
        },
        "taxonomies": [  // Additional Teams
            {
                "displayName": "Dv1",
                "type": "Division"
            },
            {
                "displayName": "Workvivo",
                "type": "Company"
            }
        ]
    }
}

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": "add",
            "path": "title",
            "value": "New Job Title"
        }
    ]
}

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
• DisplayName: Display Name
• Active: Whether the user's account should be active or deactivated
• JobTitle: User's Job Title
• DirectDial: Direct (Work) phone number
• MobilePhone: Mobile phone number
• DateOfBirth: Date of Birth
• HireDate: Hire Date
• Manager: User's Manager that generates org chart
  • Please note, this must be in Email format or WorkvivoID. If email, SCIM provider needs to be Okta in the screen shot in the beginning
     

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 secondary structure setting
• CostCenter: Tertiary structure setting

To learn more about our team types and structure settings, please visit our help center article here
 

View the clip below for a video walkthrough: