Employee API v2

Employee API v2 was introduced in the 21 August 2020 patch as an Early Adopter in conjunction with the Generally Available (GA) announcement of the OU API.

With the introduction of the following enhancements in the October '20 Release, the Employee API v2 is Generally Available:

  • Search by OU
  • Update using GUID

With v2 of this API, along with parity with v1, organizations will realize the following enhancements:

  1. Host of additional endpoints to get employee metadata information.
  2. Targeted, modular calls to allow fetching smaller payloads of specific datasets.
  3. Improved response times by ~30% for PUT/PATCH/POST and ~50% for GET endpoints.
  4. Increase throttling limit by 50% (from 100/min to 150/min, for all non-bulk endpoints)
  5. A closely coupled OU API, that will allow consumers to serve a much broader set of use-cases to create, update, and fetch employee data for specific OU's.

With these benefits in place, organizations are highly encouraged to move to v2 and start planning to move off both v1 REST API and the SOAP services.

At this time, Cornerstone has not deprecated the SOAP User/OU API, 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.

API Explorer

Documentation for all available APIs is available in the API Explorer for general access.


Organizations can purchase and enable the Employee/OU API through the Edge Marketplace as a part of Cornerstone Foundational APIs. The Employee API v2 is displayed along with the OU API as a singular tile, Employee/OU API, on the API explorer.

There are new scopes for Employee API v2 endpoints. These new scopes are visible while registering a new OAuth 2.0 application or modifying an existing OAuth 2.0 application. Organizations with existing OAuth2 apps must explicitly go in and select the Employee API v2 scopes before they can start making calls to the Employee API v2 endpoints.

Additional documentation is available in the API Explorer and it includes a link back to Employee API v1 documentation if needed.