Quick Start: Get an Employee

With the updated employee API, we support several different methods of fetching:

• ids
• userName
• externalId
• guid
• lastName
• firstName
• modifiedDate
• createdDate
• status

Typically, our lookup will take two steps:

• Lookup basic information on a user
• Fetch the details for that user

For this example, we'll use one of the most common use cases that we see: lookup by externalId and fetch additional details by id. As a reminder, externalId refers to the 'User ID' field you see in the UI (you may also know this as the 'User Ref').

Step 1: Identify the employee to lookup

We'll start by using our external ID jswift1822 to lookup our user, using the following call:

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

From the response, notice the id which we'll be using to fetch additional details for this employee.

// 200 OK
[
    {
        "id": 5646543,
        "externalId": "jswift1822",
        "userName": "johnathan.swift",
        "guid": "97eaec4f-77d8-4765-acee-d7b7312b9140",
        "firstName": "Johnathan",
        "lastName": "Swift",
        "primaryEmail": "johnathanswift@csod.com",
        "workPhone": "4245551234",
        "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": "en-US",
            "timeZone": "(UTC-08:00) Pacific Time (US & Canada)",
            "trainingApprovals": 2
        },
        "managerId": 37,
        "approverId": 38,
        "employeeMetaData": {
            "createdDate": "2008-07-02T06:33:02.000Z",
            "modifiedDate": "2019-03-14T14:11:01.000Z"
        }
    }
]

Note that while we have some basic information on this record, for details on things like OUs and custom fields, we'll have to go to the employee record using the id. The id remains constant for a given employee. If you want to reduce the number of API calls, you may want to store the id locally on your end.

Step 2: Request the detailed employee record

With the id from the call above, we're now empowered to look up details on that user, update or mark that user inactive, change localization settings, or for Cornerstone HR clients, update effective-dated information.

As you'd expect, this call is pretty simple to make, with the id value 5646543.

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

This returns us the full employee record:

// 200 OK
{
    "id": 5646543,
    "externalId": "jswift1822",
    "userName": "johnathan.swift",
    "guid": "97eaec4f-77d8-4765-acee-d7b7312b9140",
    "firstName": "Johnathan",
    "lastName": "Swift",
    "primaryEmail": "johnathanswift@csod.com",
    "workPhone": "4245551234",
    "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": "en-US",
        "timeZone": "(UTC-08:00) Pacific Time (US & Canada)",
        "trainingApprovals": 2
    },
    "managerId": 37,
    "approverId": 38,
    "relations": [
        {
            "id": 38,
            "typeId": 4
        }
    ],
    "ous": [
        {
            "id": 231568,
            "typeId": 2
        },
        {
            "id": 1858,
            "typeId": 4
        }
    ],
    "customFields": [
        {
            "id": 36,
            "value": "Jack"
        },
        {
            "id": 37,
            "value": "123902"
        }
    ],
    "employeeMetaData": {
        "createdDate": "2008-07-02T06:33:02.000Z",
        "modifiedDate": "2019-03-14T14:11:01.000Z"
    }
}

Please note, there are a few things that are NOT available in this call, and will require additional calls:

• Employment status (GET /services/api/x/users/v2/employees/5646543/employment-status)
• Activation Period (GET /services/api/x/users/v2/employees/5646543/activation-period)
• Groups (GET /services/api/x/users/v2/employees/5646543/groups)

Additionally, there are some items that are ONLY available through the UI:

• Encrypted custom fields
• Secured custom fields
• Other SPII fields such as birth dates and social security numbers