Cornerstone provides our customers and partners the ability to easily integrate with Cornerstone using APIs (web services). APIs provide instant and programmatic access to Cornerstone data to support domain and reporting use cases. This includes on-demand access to do the following:
- Read data from Cornerstone.
- Create and update data in Cornerstone.
Implementation
The customer is responsible for any infrastructure and development to call or execute Cornerstone APIs. Cornerstone does not offer to develop custom code or custom APIs, and Cornerstone does not develop or debug customer's source code.
Terminology
The following terms are commonly used when discussing APIs:
- REST (Representational State Transfer) - An architectural style for providing standards between systems on the web, making it easier for systems to communicate with each other.
- OData (Open Data Protocol) - An open protocol (OASIS standard) that defines best practices for building and consuming RESTful APIs.
- SOAP (Simple Object Access Protocol) - An XML-based protocol for exchanging structured information across domains.
- JSON (JavaScript Object Notation) - A lightweight and text-based data-interchange format. JSON has become one of the fundamental industry standards to exchange data via web services because it is easy for humans to read and write and also easy for machines/browsers to parse and generate.
- OAuth 2.0 (Open Authorization) - An industry standard authorization framework that supports the consumption of RESTful APIs.
- Any new integrations built using Cornerstone's APIs must use OAuth 2.0.
- For more information, please visit: http://apiexplorer.csod.com/apiconnectorweb/apiexplorer#/oauth
API Explorer
API Explorer contains the most up-to-date documentation for all REST APIs. API Explorer enables developers and partners to easily browse all available REST APIs. Developers can learn about supported features, methods, and metadata. Developers can also download guidelines and access links to sample code.
To access the Developer Portal, go to . Developer Portal can also be accessed directly at the following URL: https://csod.dev
Release Strategy
All clients reside on the same and latest web services version. New web services will be developed and deployed as part of the roadmap. Cornerstone does not support building custom APIs for each customer use case.
All new APIs will be developed as RESTful APIs. Any legacy SOAP web services that are still available are maintained, but they will not be further developed.
Trial Period
An unlimited trial period is available to try the Cornerstone APIs, Reporting APIs, or Bulk APIs. The trial period is available for non-productive environments (i.e., pilot, stage, and demo environments). To try an API, simply instal the integration in your Pilot, Stage, or Demo environment. The integration must be configured in each environment separately.
Pagination
To increase performance and to minimize the response size, Cornerstone web services utilize paging in its response. This means the caller will only retrieve a page of results, and not all the entities. Please review the API Explorer for the default and the maximum paging values per web service request.
- Cornerstone API - The Cornerstone API must be sequentially called by incrementing the page number attribute in the URL query until Cornerstone stops returning results.
- Reporting API - The Reporting API implements OData server-driven paging protocol. The service will inject a link into the page response to retrieve the next page of results.
- Employee/OU API - Customers can control the number of records per page through the pageSize query parameter. The service will inject into the page response an encoded string named nextPageToken that is used to retrieve the next page of results. The nextPageToken has a time to live (TTL) of five minutes.
Registering an Application
Every application that you intend to integrate using Cornerstone's APIs and OAuth 2.0 must be registered within the Cornerstone Edge API Management page. This can be done by going to
You can register multiple applications with Cornerstone to get a distinct client ID and secret for each application. A client ID and client secret are required to consume RESTful APIs. Note: The client secret is only displayed once, so be sure to copy it after registering an application. If you misplace the client secret, you must regenerate it in the Cornerstone portal.
Access can be provided to multiple APIs (e.g., Cornerstone APIs and Reporting APIs) at the same time. This can be specified when registering the application.
When registering an application, the OAuth 2.0 access token validity period can be configured.
Sample Code
The Cornerstone GitHub repository contains sample code for several APIs and in popular development languages.
https://github.com/cornerstoneedge
OAuth 2.0 Scopes, Security Permissions, and Constraints
Using Scopes, organizations can control the API endpoints to which an application has access and the HTTP operations (GET, POST, PUT, PATCH) which can be performed against those endpoints. For example, an organization may grant their application access to only read employee data.
Scopes are available for all RESTful APIs. The API Explorer contains which scope is required to execute a specific endpoint or HTTP operation. See Edge - API Explorer.
Certain APIs allow organizations to further restrict an application's access using security permissions and constraints. For example, with the Express Class API, organizations can choose to allow their application to create express class records users from a specific division or geographical region. To determine whether an API requires permissions and supports constraints, review the list of permissions required for each API and the descriptions of each permission. See API (Web Services) Technical Specifications.
The following HTTP operations may be available for an API:
- GET - Read data
- POST - Create new data
- PATCH/PUT - Update existing data
- In Cornerstone, some web services supporting PATCH, others are supporting PUT to update data. With PUT request, you must send the full payload as the request whereas with PATCH, you only send the parameters which you want to update.
The OAuth 2.0 framework describes several grant flows or methods for acquiring an API access token. Cornerstone only supports the Client Credentials grant flow.
Frequently Asked Questions (FAQs)
Is it possible to provide an application only with access to create and retrieve learning data from Cornerstone, but not to retrieve Employee data?
Yes, this can be done by selecting only the API endpoints required to create or retrieve learning data.
Is it possible to restrict access for an endpoint to specific data only?
Certain endpoints allow you to further restrict your application’s access using security permissions and constraints.
If a specific endpoint does not support constraints, this type of security must be managed by the customer.
Why do the custom field names look different in the API explorer per portal?
The API explorer shows the current portals’ configuration.
What is the difference between a scope and a permission?
Not all APIs have permissions, but all APIs have scopes.
Most APIs require both: A scope to be assigned to the OAuth 2.0 application and token and security permissions to be assigned to the user tied to the OAuth 2.0 application
Where can I find the legacy SOAP documentation?
All Cornerstone SOAP APIs will be deprecated in Q4 of 2023.
Are API keys overwritten during a copy down?
No, copy downs do not impact API keys or any Edge integrations.
Content
The following information is available within this folder. Click a link to navigate directly to the appropriate topic: