# Introduction

The Employee/OU API allows you to create, update, and fetch employee and organizational unit (OU) details from Cornerstone.

# Evolution of Cornerstone's Employee/OU APIs

Over the last few years, Cornerstone has provided the User/OU SOAP API, the Employee API, GET OU API, the Bulk API, and now the Employee/OU API. The table below describes the current state of each of these APIs.

Feature User/OU SOAP API Employee API GET OU API Bulk API Employee OU/API
Endpoints /feed30/clientdataservice.asmx /services/api/x/users/v1/employees/* /services/api/OrgUnits/OU /services/api/x/bulk-api/v1/* /services/api/x/users/v2/employees/*
/services/api/x/organizations/v1/ous/*
Technology SOAP REST REST REST REST
Supported Operations Create, read, update Create, read, update Read Create, update Create, read, update
Bulk Load Supported? Yes Up to 500 records per call No N/A Yes
Can be used by Cornerstone HR clients? No Yes Yes Not yet Yes
Ongoing Support? No
(deprecated)		 Yes Yes Yes Yes
Future Enhancements? No No No Yes Yes

Note that, at this time, Cornerstone has NOT deprecated the employee API v1, or the GET OU API. We will continue to address defects and questions with these endpoints. However, any enhancements will only be made to the Bulk API and the Employee/OU API. If/when we decide to deprecate the older endpoints, you will see an update on this page. Clients and partners will also be made aware through the regular release communication channels.

# New API Design

If you've integrated with Cornerstone previously, you'll notice that the design of these APIs is substantively different than many of our previous APIs. Specifically, there are four key differences:

  • Smaller API calls. Previously, we've attempted to return every attribute associated with a resource in a single call. However, as the adoption of our APIs has increased, these heavy calls result in higher resource utilization on our end which in turn impacts API response times negatively. Thus, while these calls could return data required for any use case, they weren't scalable for heavy adoption. Starting with the Employee/OU API, we are changing our overall API design principle to support smaller, modular response payloads. This might require you to make more API calls to retrieve all the data you need, but in return, you get better response times and higher throttling limits.
  • Paging Token. Similar to the Reporting API, we have added paging tokens to the Employee/OU API as well. This further improves the performance and prevents accidental over-paging of our resources. See the 'Pagination' section below for additional details.
  • Higher throttling limit. Based on these improvements, we are able to significantly increase our throttling limit. For example, instead of sharing the '429 per minute limit' shared across endpoints in the Core/HR, Learning, Performance, and Recruiting APIs, each OU endpoint alone in the Employee/OU API will permit 300 calls per minute. For those of you doing math, if you add up the limits across all the OU endpoints, we'll be permitting 3,000 calls/minute, a 600% increase.
  • Renaming OuId and UserId to ExternalId. In addition to these technical changes, you'll also notice some differences around field names. For this change, in particular, fields can behave more predictably—fields that are simply ID will be our primary key, and externalId will always be the client-facing ID, regardless of which API you're using.

# Employee API v2

The Employee/OU API contains enhanced versions of the Employee API endpoints. For the sake of clarity, we will refer to these new endpoints as Employee API v2 and the older endpoints as Employee API v1. You will also see the version number in the endpoint URL (for example, /services/api/x/users/v2/employees). If you currently use the [Employee API v1 endpoints (/services/api/x/users/v1/employees/\*), we highly encourage you to consider moving to the v2 endpoints. The v2 endpoints have,

  • Better performance with modular endpoints
  • Higher throttling limits
  • Better ability to search for an employee

# Employee/OU API vs. the Bulk API

The Bulk API is optimized for loading large data sets in an asynchronous, queued model. It's ideal for bulk load use cases where you wish to create or update data into your Cornerstone portal using APIs. For example, you can use Bulk APIs to keep employee and OU data in sync from your HRIS into Cornerstone. The Bulk API isn't ideal for real-time or near real-time integrations that are triggered based on user actions in an external application. This is because the Bulk API does not process data synchronously which means you cannot provide immediate feedback to the user. For example, if an admin creates a new employee in your HRIS and they wish to see a confirmation that the record has also been created in Cornerstone, the Bulk API isn't your best option. In such scenarios, you should use the Employee/OU API.

Additionally, if you wish to retrieve data from your Cornerstone Portal, the Bulk API is not an option. The Bulk API only supports loading data into Cornerstone. There is no GET facility. To retrieve data from Cornerstone, consider using either

The table below summarizes the differences between the two APIs.

Feature Employee/OU API Bulk API
Real-time Yes No
Bulk Create/Update No Yes
Read Yes No
Ideal Use Case Real-time transactional integrations Sync-based integrations
API Product Offering Requires Purchase of Cornerstone API Requires Purchase of Bulk API