The Employee/OU API allows organizations to create, update, and fetch employee and organizational unit (OU) details from Cornerstone. The Employee/OU API appears as a single tile in API Explorer, and it includes two APIs:
- Employee API v2 contains the following enhancements:
- Host of additional endpoints to get employee metadata information.
- Targeted, modular calls to allow fetching smaller payloads of specific datasets.
- Improved response times by ~30% for PUT/PATCH/POST and ~50% for GET endpoints.
- Increase throttling limit by 50% (from 100/min to 150/min, for all non-bulk endpoints).
- 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.
- The Organizational Unit (OU) API provides robust handling for full feature management of OUs. The OU API is now in General Availability with the release of Employee API v2. Detailed API documentation can be found in the Edge API Explorer.
Organizations are highly encouraged to move to Employee API v2 and start planning to move off both Employee API 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. Cornerstone 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.
Employee API
The Employee API includes the following services:
- Get - Return User record details including Effective Date (CHR) support.
- Create/Update - Insert or update user records including Effective Date (CHR) and custom fields support. This includes data related to employee termination (e.g., employment status, termination date).
- Activation Period - Return and update the activation period of an employee record.
- User Effective Dates - Return all effective dates associated to a user record.
- Custom Fields - Return custom field data for employees.
- Groups - Return employees and the groups in their employee profile.
- User type and Employment Status -
- Return User type and Employment status details including Effective Date (CHR) support Employment status.
- Insert and update User type and Employment status data incl. Effective Date (CHR) support.
Organizational Unit API
The Organizational Unit API includes the following services:
- Get - Get organizational unit details
- Set - Insert or update organizational unit records
API Explorer
Documentation for all available APIs is available in the API Explorer for general access.
Considerations
- Access to data via the Employee API v2 can be constrained using the permission.
- The OU API leverages the same permissions and constraints required to manage OUs in the portal.
- Group management is not supported with this API.
Implementation
Organizations can purchase and enable the Employee/OU API through the Edge Marketplace as a part of Cornerstone Foundational APIs. There are new scopes for API endpoints.
For full documentation about the API, please see the API Explorer: https://apiexplorer.csod.com/apiconnectorweb/apiexplorer#/
Permissions
The API respects the same permissions and constraints on the following permissions:
| PERMISSION NAME | PERMISSION DESCRIPTION | CATEGORY |
| Employee API - Edit |
Grants ability to use the Employee API v2 to create and update users. This permission can be constrained by OU and User's OU. The constraints on this permission limit what data is accessible via the Employee API v2. This is an administrator permission. This permission is only available when the Employee API v2 is enabled via Edge Marketplace. |
Edge |
| Employee API - View - Constrained |
Grants ability to use the Employee API v2 to view employee data with constraints. This permission can be constrained by User, OU, and User's OU. The constraints on this permission limit what data is accessible via the Employee API v2. This is an administrator permission. This permission is only available when the Employee API v2 is enabled via Edge Marketplace. |
Edge |
| Employee API - View |
Grants ability to use the Employee API v2 to view employee data. This permission can be constrained by OU, and User's OU. The constraints on this permission limit what data is accessible via the Employee API v2. This is an administrator permission. This permission is only available when the Employee API v2 is enabled via Edge Marketplace. |
Edge |
| OU Hierarchy - Manage | Grants ability to create and update/edit organizational units. This permission grants access to all OU types, both standard and custom. This permission can be constrained by OU and User's OU. This is an administrator permission. | Core Administration |
| Grades - View | Grants ability to view the Grade Organizational Unit throughout the system, such as in availability drop down selectors, when editing users, etc. Those without this permission do not see the Grade OU on any screen. This is primarily an administrator permission, although organizational policy should determine whether the Grade OU should be visible to end users on reporting screens, etc. | Core Administration |