Introduction

TIP

View the Core/HR API Reference Guides

Cornerstone's Bulk API provides you the ability to create and update your organization's data in Cornerstone. The Bulk API is RESTful, uses OAuth 2.0 for authentication, and is built on top of a scalable and resilient data load framework. Currently, Cornerstone supports loading the following data types via the Bulk API:

• Employee
• Organizational Unit (Cost Center, Division, Grade, Legal Entity, Location, Position, and Custom OUs)
• LMS Historical Data
• Capabilities

Considerations

• The Bulk API currently does not support loading data to secure custom fields and sensitive personally identifiable (SPII) fields.

Ideal Use Case

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. In this example,

• You would setup the sync process to trigger at frequent intervals (daily, weekly, several times in a day, etc.) automatically from your HRIS without requiring any user input.
• You would have a process to verify the results of the load asynchronously. In most cases, records that failed to load due to errors would require human intervention to fix the source data.

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. You may wish to use the Employee API in that scenario. On the other hand, if your use case requires creating or updating thousands of employee records asynchronously within a reasonable duration, the Bulk API is your ideal solution.

Finally, if you wish to retrieve data in bulk 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 in bulk from Cornerstone, consider using the Reporting API.

Enable Bulk API

You can enable the Bulk API for free in your pilot and stage portals by following these steps:

1. Log in to your Cornerstone portal in the stage or pilot environments. Navigate to Admin > Tools > Edge > Marketplace.
2. Search for and click on the 'Bulk API'.
3. Read the information about the Bulk API and click 'Install'.
4. Read and accept the terms and conditions and click 'Install' again.
5. Click on Manage APIs in the confirmation dialogue.
6. Toggle the 'Bulk API' on.

To use the Bulk API in production, you will need to purchase it. The annual recurring fee varies by the number of licensed users in your portal. Please reach out to your Cornerstone Account Manager to get details on the pricing. You can submit a purchase inquiry through the Edge Marketplace. Follow these steps to submit a purchase inquiry:

1. Login to your production Cornerstone portal.
2. Search for and click on the 'Bulk API'.
3. Read the information about the Bulk API and click 'Purchase Inquiry'.
4. Complete and submit the form. We will route your purchase inquiry to your Account Manager who will reach out to you with next steps.

Disabling the DLW

To load employee and organization unit (OU) data using the Bulk API, you must permanently turn off the corresponding Data Load Wizard (DLW) loads and feeds in your portal. We do this to ensure that we don't run into data contention issues should users end up loading the same data at the same time through the DLW and the Bulk API.

• If you attempt to use the Bulk API to load employee/OU data while the corresponding DLW loads are turned on, you will see the following error message in the Bulk API load results: HR data cannot be loaded while Data Load Wizard (DLW) is enabled.
• To disable the DLW, navigate to Admin > Tools > Edge > Imports and Feeds > DLW Migration > 'Disable DLW' tab > Click on the 'Disable' button for HR. You need the 'Disable Data Load Wizard' permission to access this tab.

If you currently use the DLW to perform User/OU loads and would like to continue to have the ability for users in your organization to perform loads/feeds using a UI-based tool, we highly recommend that you consider switching to Edge Import. Administrators in your organization can use Edge Import to load data and set up feeds using a simple and intuitive user interface. And unlike the DLW, you can use the Bulk API and Edge Import in parallel.

Basic Concepts

The Bulk API uses certain terms that are unique to bulk operations. Familiarize yourself with these terms before reading the rest of the documentation:

• Schema: The schema defines the fields and field properties for each data type. Since Cornerstone is a highly configurable system, the schema varies from portal-to-portal. For example, in the employee schema, it accounts for custom fields, custom OU, and custom relationships. In the OU schema, it accounts for custom OUs. The schema can also vary by the configuration.
• Job: A job is a container for your bulk load operation. Each job can contain several imports. For example, you can load employee, division OU, and location OU data in a single job.
• Import: An import is a data load of a particular type. For example, a request to load employee data is an instance of an import. As stated above, a job can contain several imports.

If you are familiar with Cornerstone's transactional APIs, note that the Bulk APIs work a bit differently. The diagram below illustrates the steps you will need to take. A description of each step follows the diagram.

• Design: While designing your integration, you will need to execute the following steps:
  • Get Schema: Due to Cornerstone's configurable nature, the data model for each organization that uses Cornerstone can vary. As a result, the first step you will want to take while building any integration is to get the schema for the data you wish to load. The schema endpoint's response contains the list of fields and the validation metadata for each field, including the field type, description, max and min length. It also indicates which fields are required, the list of accepted values for certain fields, and the list of conditionally required fields.
  • Prepare Data Template: Using the schema, you will construct your data template in JSON or CSV format, the two data formats the Bulk API accepts. You will need to include all the required fields and any additional fields you wish to load using the Bulk API.
• Ongoing Execution: While developing your integration using the Bulk API, you will need to schedule the following steps to occur in sequence at your desired frequency. For example, if you wish to sync employee data from your HRIS into Cornerstone on a daily basis, you should schedule these jobs to occur once everyday on your end.
  • Create Job: A job is a container for your bulk load operation. Each bulk load operation must start with the creation of a job. In the request to create a job, you will include the types of data you wish to load along with the associated settings. You can also optionally include a callback URL for Cornerstone to post a message when the job completes execution. For each job you create, Cornerstone will provide a unique Id.
  • Load Data: An import is a data load of a particular type. This is where you will include the data you wish to load in the request body using the template you prepared in step #1b above. You will need to create an instance of an import for each data type you wish to load.
  • Check Job Status: Once you have loaded the data using the import endpoint, you should check the status of your job. You can do this in one of three ways:
    • Setup a webhook endpoint on your end and send it to Cornerstone as a callback URL in the job request. When the job completes, Cornerstone will post a message to your callback URL.
    • Call the jobs endpoint with the Id Cornerstone returned in the Create Job step. This provides you the status, the number of records in your import, the number of records loaded successfully, the number of records loaded with warnings, and the number of error records.
    • Review the status of the job in the Bulk API History page in your Cornerstone portal. This is ideal for an administrator who has access to your Cornerstone portal.
  • Retrieve Import Results: Once you know that Cornerstone has completed executing your job, you can get the results of each import using the import endpoint. You can retrieve a report containing the warning and error records for each import, including the warning/error reason. You can retrieve these reports through the Bulk API History page as well.

Specification

If you wish to retrieve the entire specification for the Bulk API in a given client portal you can use the /services/api/x/bulk-api/v1/specification endpoint. A successful response includes an OpenAPI v3 compliant specification that you can copy and paste into an editor such as https://editor.swagger.io. You may want to use this option if you are familiar with a Swagger specification. If you are loading custom OUs, you will need to use this endpoint to retrieve the custom OU type_id and use it in your schema and job requests.