Quick Start: Update an Employee

For updating an employee, we'll combine some of the concepts from our other quick start sections. Specifically, we'll be updating an employee's OU structure. To do this, we'll need two items:

• The id of the OU that we'll be adding
• The id of the user that will be getting the additional OU

For this example, we'll be using the OU ID of the OU we created in the Quick Start: Creating an OU section, and the Employee we created in the Quick Start: Creating an Employee section. So, we'll need to:

1. Fetch the OU
2. Fetch the Employee
3. Update the Employee
4. Validate the Update.

Step 1: Fetch the OU

We'll begin by requesting our OU with the externalId that we have in our HRIS system. This is the same value that we used when creating the OU: d04523.

GET /services/api/x/organizations/v1/ous?externalId=d04523
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

This will give us the basic information on the OU that we created. As a reminder, we updated the name of this OU in the Quick Start: Updating an OU section. You will see that updated name here.

// 200 OK
{
"timestamp": "2020-06-27T14:12:12.537479",
"pageNumber": 1,
"count": 2,
"data": [
{
"id": 9025,
"typeId": 2,
"active": true,
"name": "Integration and Services",
"externalId": "d04523",
"ownerId": 123,
**"description": "The Integration and Services division",**
"parentId": 186,
"reconcilable": true,
"customFields": [
{
"id": 579,
"value": "269"
}
]
}
]
}

So we've found our ID once again: 9025, and it's type: 2.

Step 2: Fetch the Employee

Now that we've retrieved the ID for our OU, we can fetch our employee once again. As a reminder, we'll use our externalId as our key to fetch this ID:

GET /services/api/x/users/v2/employees?externalId=tsmith482
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

We'll once again retrieve the basic data on this employee:

// 200 OK
[
    {
        "id": 48928,
        "externalId": "tsmith482",
        "userName": "thomas.smith",
        "firstName": "Thomas",
        "lastName": "Smith",
        "middleName": "Paul",
        "primaryEmail": "t@smith.com",
        "workPhone": "3105551234",
        "address": {
            "country": "US",
            "line1": "1601 Cloverfield Blvd",
            "city": "Santa Monica",
            "state": "CA",
            "zipCode": "90404"
        },
        "workerStatus": {
            "lastHireDate": "2008-07-04",
            "originalHireDate": "2018-12-31",
            "active": true,
            "absent": false
        },
        "settings": {
            "displayLanguage": "es-ES",
            "timeZone": "(UTC-12:00) International Date Line West"
        },
        "managerId": 37,
        "employeeMetaData": {
            "createdDate": "2020-07-05T06:33:02.000Z",
            "modifiedDate": "2020-07-05T06:33:02.000Z"
        }
    }
]

Step 3: Update the Employee

Now that we have the ID (48928), we're ready to perform our update. This time, we'll perform a patch:

PATCH /services/api/x/users/v2/employees/48928
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
{
    "ous": [
        {
            "id": 9025,
            "type": 2
        }
    ]
}

And that's it! All we need to pass in is the data that we're wanting to update, and we'll get a 204 No Content response, indicating a success.

Step 4: Validate the Employee

For our last optional step, we'll want to validate that our change worked. We'll perform a GET on the employee details to see their OU membership:

GET /services/api/x/users/v2/employees/48928
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

From here, we see that the OU was updated. Since this was an OU he already belonged to, it updated the OU of that type (since employees can only belong to one OU of a given type at a time):

// 200 OK
{
"id": 48928,
"externalId": "tsmith482",
"userName": "thomas.smith",
"firstName": "Thomas",
"lastName": "Smith",
"middleName": "Paul",
"primaryEmail": "t@smith.com",
"workPhone": "3105551234",
"address": {
"country": "US",
"line1": "1601 Cloverfield Blvd",
"city": "Santa Monica",
"state": "CA",
"zipCode": "90404"
},
"settings": {
"displayLanguage": "es-ES",
"timeZone": "(UTC-12:00) International Date Line West",
},
"managerId": 37,
"ous": [
{
"id": 9025,
"typeId": 2
}
],
"customFields": [
{
"id": 37,
"value": "123919"
}
]
"employeeMetaData": {
"createdDate": "2020-07-05T06:33:02.000Z",
"modifiedDate": "2020-07-06T12:22:00.000Z"
}
}

And that's it! We've successfully updated the employee record.