# Introduction

The POST Candidate and Application API provides the ability to create an application and candidate in Cornerstone. Applications may be posted in a complete or incomplete status. If incomplete, recruiters will be able to invite candidates to finish their application within the ATS. If the candidate already exists, the application will be added to the already existing candidate. The POST Candidate and Application API can, but is not required to be used with the GET Application Workflow API, and the GET Requisition API. An ideal use case for this API is to add a candidate to Cornerstone after applying via an externally hosted career site or via chat, or when a Recruiter would like to add a candidate to Cornerstone from a Candidate Relationship Management Tool (CRM).

An example use of this POST endpoint:

  1. A chatbot provider is supporting a "chat to apply" experience and would like to create a candidate and application in Cornerstone
  2. You are hosting your own candidate experience via an alternate recruiting solution and would like to create a candidate and application in Cornerstone when the candidate submits their application
  3. An external job board would like to post applications to Cornerstone with answers to prescreening questions, compliance questions, and disclaimers
  4. Candidate Relationship Management Tools would like to post candidates with a complete or incomplete application to Cornerstone

The required fields in order to create a candidate and application are firstName, lastName, jobRequisitionId and email. The POST Candidate and Application endpoint is not dependent on the GET Application Workflow endpoint, and will not validate against that requisition's required application workflow questions, with the exception of phoneNumber. Clients configure phone numbers to be required or optional at a portal level, and is used to identify potential duplicate accounts. An API consumer can determine if the phoneNumber should be required or optional, by calling the GET Application Workflow endpoint, or by checking the portal configurations in Applicant Preferences Recruiting Admin Settings.

An API consumer must know a requisition ID prior to posting a candidate and application. This can be found via the Get Job Requisition endpoint (information found here), a job distribution connector, or other source. The requisition must be in an 'open' or 'open pending re-approval' status and posted to at least one Cornerstone career site in order for an application and candidate to be added via the POST Application and Candidate endpoint. The requisition posting should also be active at the time of application submission. Requisitions must be posted to a career site so that an applicant can finish an application when invited to do so by a recruiter.

The POST Candidate and Application endpoint will check an applicant's eligibility to apply to a position from their email address. If the candidate already exists in the system, and they are eligible to apply to the position, the application will be added to the existing candidate's profile. The new API can also be used to add internal applications to internal candidates. While not required, API consumers may call Cornerstone's Employee Global Search API or Core's Global Search API to determine if a candidate is an internal or external candidate (documentation found here). This will enable the API consumer to request the correct application workflow- Internal or External. Otherwise, the POST Candidate and Application endpoint will check the candidate's email address.

# Throttling

To ensure the best possible performance of the Candidate API for all Cornerstone clients, we have implemented throttle limits. Throttle limits apply to all authenticated APIs calls. If a request is made after the throttle limit is reached, an HTTP error is thrown, which is to be handled elegantly. We recommend that interface applications queue such requests until the throttle limit duration has passed and the request can be re-sent. If either the throttle limit or request frequency is exceeded, an error will be thrown, and must be handled. The POST Candidate and Application endpoint will allow for 50 requests per minute.

# POST Candidate and Application API Compared to Job Application API

If your applications consist of more than a resume and cover letter, and frequently include prescreening questions, compliance questions or disclaimers, and you do not want to redirect candidates to your Cornerstone Career Site to finish their application, we recommend writing to our new POST Candidate and Application endpoint, rather than our legacy Job Application API. Cornerstone's new POST Application and Candidate endpoint is flexible and allows API consumers to post as little as a candidate's first name, last name, job requisition ID, and email, or as much as the full application without validating against the job requisition. The legacy Job Application API was built with the intention of integrating with Stepstone and other job boards that have candidate involvement. The API could also be used for clients with very simple application workflows (i.e., just a resume). We have no plans to deprecate the legacy Job Application API, as select vendors only post a resume and cover letter to Cornerstone.

# Permissions Required

No new permissions are required to leverage the POST Candidate and Application API. However the following existing permissions apply to enablement:

  • Edge Integrations–Manage: Grants access to the Integrations service for Edge Integrate where the administrator can configure, enable, and disable their third-party integrations that are used within the Cornerstone system. This permission cannot be constrained. This is an administrator permission
  • Edge Marketplace–Manage: Grants access to the Marketplace service for Edge Integrate where the administrator can browse and purchase integrations that can be used to extend the Cornerstone system. This permission cannot be constrained. This is an administrator permission.