Core/HR - Examples

This page contains various examples how to use the Core/HR web services.

{URL}: For simplicity, we are using a {URL} tag. For these examples, replace the {URL} tag with the virtual path to the portal, for example: {URL}/users/v2/employees will become https://portalname.csod.com/services/api/x/users/v2/employees

Response: The response examples are shortened extracts to simplify visibility.

Use Case 1: Fetch employee records using various filters.

Note that the response may include paging to segment large results of data into pages.

Example	Operator	Syntax
All user records		{URL}/users/v2/employees
User record, filtered by User Id 'p.abbot'	equal (text)	{URL}/users/v2/employees?externalId=p.abbot
User records, filtered by last name	equal (text)	{URL}/users/v2/employees?lastName=abbot
All active users	equal (text)	{URL}/users/v2/employees?status=active
All user records created on 15-Jun-2022	equal (date)	{URL}/users/v2/employees?createddate=2022-06-15

Use Case 2: Get all employees for a specific OU.

For this use case, we want to query all employees in the 'Sales' division. The first step is to identify the internal OU id before being able to query the actual user data.

API Call 1: Get the internal OU id for the Sales division.

{URL}/organizations/v1/ous?externalId=Sales

Response: As a response, we will get the internal OU Id, in this example: 897

{
      "id": 897,
      "active": true,
      "name": "Sales",
      "externalId": "Sales",
      "typeId": 2,
      "ownerId": null,
      "description": null,
      "parentId": 1638,
      "reconcilable": false
}

API Call 2: With the internal OU id, we can now query for all employees in this division. Please note that the query does not automatically include subordinates, but the query parameter for OU id supports to provide a list of active Organization Units.

{URL}/users/v2/employees?ous=897

Response (extract): All users in division Sales (OU Id 897).

{
      "id": 143,
      "externalId": "cbaumann",
      "userName": "cbaumann",
      "guid": "65062278-5de8-485e-a575-defa0208e61c",
      "firstName": "Christian",
      "lastName": "Baumann",
      "middleName": null,
      "prefix": null,
      "suffix": null,
      "primaryEmail": "cbaumann@demo.com",
      "personalEmail": null,
      "homePhone": null,
      "mobilePhone": "+49 177 111 222",
      "workPhone": "+49 211 4567 1234",
      "fax": null,
      "address": {
        "country": "DEU",
        "line1": "Friedrichstrasse 58",
        "line2": null,
        "city": "Düsseldorf",
        "state": null,
        "zipCode": "40235"
      },
      "workerStatus": {
        "lastHireDate": "2007-08-17T00:00:00",
        "originalHireDate": "2007-08-17T00:00:00",
        "active": true,
        "absent": false
      },
      "settings": {
        "displayLanguage": "de-DE",
        "timeZone": "(UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna",
        "trainingApprovals": 0
      },
      "managerId": 148,
      "approverId": 148,
      "employeeMetaData": {
        "createdDate": "2007-08-17T00:00:00",
        "modifiedDate": "2019-12-15T21:54:48"
      }
}

Use Case 3: Get Employee data using the internal User Id.

The employee endpoint supports to use the (unique) internal User Id as a Url parameter to return the employee data for a specific user. Note: In using this format, the API will add additional fields like the user's organizational data or the user's custom fields into the response.

API Call 1: Get the internal user Id for the User Id 'p.abbot'

{URL}/users/v2/employees?externalId=p.abbot

Response (extract): As a response, we will get the internal user Id, in this example: 1958

{
      "id": 1958
}

API Call 2: Get employee data incl. additional fields (OU data, custom fields)

{URL}/users/v2/employees/1958

Response (extract): As a response, we will get the employee data, including OU and custom field data

{
    "id": 1958,
    "externalId": "p.abbot",
    "userName": "p.abbot",
    "guid": "fbf53a48-fad9-4f88-9588-6984fcfb8c3a",
    "firstName": "Paul",
    "lastName": "Abbot",
    "middleName": null,
    "prefix": "Mr.",
    "suffix": null,
    "primaryEmail": "paul.abbot@green-consulting.com",
    "personalEmail": null,
    "homePhone": null,
    "mobilePhone": null,
    "workPhone": "210-869-1768",
    "fax": null,
    "address": {
      "country": "USA",
      "line1": "2023 Greg St",
      "line2": null,
      "city": "Speaks",
      "state": "TX",
      "zipCode": "77985"
    },
    "workerStatus": {
      "lastHireDate": "2015-05-04T00:00:00",
      "originalHireDate": "2015-05-04T00:00:00",
      "active": true,
      "absent": false
    },
    "settings": {
      "displayLanguage": "en-US",
      "timeZone": null,
      "trainingApprovals": 0
    },
    "managerId": null,
    "approverId": null,
    "relations": null,
    "ous": [
      {
        "id": 1638,
        "typeId": 2
      },
      {
        "id": 821,
        "typeId": 4
      },
      {
        "id": 1433,
        "typeId": 8
      },
      {
        "id": 763,
        "typeId": 32
      }
    ],
    "customFields": [
      {
        "id": 113,
        "value": "1234567890"
      },
      {
        "id": 117,
        "value": 118
      }
    ],
    "employeeMetaData": {
      "createdDate": "2021-12-20T12:17:38.147",
      "modifiedDate": "2022-06-09T13:01:53.737"
    }
}

Use Case 4: User Custom Fields.

In this use case, we want to identify some custom user field information (Marital status and Passprt Number) for Paul. In the previous use case, we already have identified the custom field data for Paul. The response may include the real value already (e.g. for text fields) or an Id reference only (e.g. for drop down fields).

Previous Response (extract):

{
    "customFields": [
      {
        "id": 113,
        "value": "1234567890"
      },
      {
        "id": 117,
        "value": 118
      }
    ]
}

API Call: Get custom field configuation.

{URL}/users/v2/employees/custom-fields

Response (extract):

{
  "id": 113,
  "name": "Passport Number",
  "required": false,
  "type": "ShortTextBox",
  "options": null
},
{
  "id": 117,
  "name": "Marital Status",
  "required": false,
  "type": "RadioButton",
  "options": [
    {
      "id": 117,
      "title": "Single"
    },
    {
      "id": 118,
      "title": "Married/Partner"
    }
  ]
}

Compining our findings together, Paul's Passport Number is 1234567890 and his Marital status is Married/Partner.