# Candidate

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.

# Use Cases

Cornerstone's new Candidate APIs provide the ability to get a requisition's full application workflow including prescreening questions, compliance questions, disclaimers, notes, and attachments, and 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.

Below are example uses of both the GET Application Workflow and POST Candidate and Application endpoints:

# Chat Bots

  • John Smith goes to ABC Company's Career Site to search for a Software Engineers.
  • John sees ABC offers a chat feature on their career site.
  • Rather than spending time searching for a job, John engages with the chat bot regarding Engineering type roles.
  • The chat provider writes to CSOD's Job Requisition APIs (Get Job Requisition, Get Job Ad Details, and Get Job Requisition Custom Fields) so they can recommend jobs to John based on job descriptions and location.
    • Tip: We recommend also writing to the Get Job Requisition Custom Fields endpoint as many clients use custom fields to specify fields unique to their organization
  • The chat provider identifies a Software Engineering position, Req123 as a great recommendation and asks if John would like to apply to this position.
  • When John says yes, the chat provider calls the GET Application Workflow endpoint requesting the application details for Req123. The chat provider may also check if the candidate is an internal or external candidate by calling our Employee Global Search API so they can request the correct application workflow, however this is not required.
  • Rather than sending John to another page to complete the application, John answers all application questions within the chat experience increasing ABC's chance of a successful application submission.
  • After answering the last application question, John says he is ready to submit his application.
  • The chat provider calls the second endpoint, POST Application and Candidate, to create a new user in Cornerstone, and create John's application.
  • Req123 has been configured so all new applicants go straight to the "In Review" status, rather than the New Submission status.
  • Req123 has also been configured to automatically assign an assessment to all applicants in the "In Review" status.
  • Once John's application is created, he receives ABC's Apply as Guest Application Submission Email Confirmation and is automatically assigned the assessment.
  • Recruiters now see John applied to req123 and can review his resume, contact details, and all posted application responses. Recruiters can also see that the assessment was successfully assigned.

# Job Boards

  • Denise goes to her favorite job board, Work4You, to search for Software Engineering jobs in her area.
  • Work4You writes to CSOD's Job Requisition APIs (Get Job Requisition, Get Job Ad Details, and Get Job Requisition Custom Fields) to display all jobs posted by their mutual client, ABC as search results.
    • Tip: We recommend also writing to the Get Job Requisition Custom Fields endpoint as many clients use custom fields to specify fields unique to their organization
  • Denise finds 10 Software Engineering roles matching her zip code.
  • After reading the job details, Denise is interested in ABC's Software Engineer role, Req 123 and clicks "Apply Now" on the job board.
  • Work4You calls the GET Application Workflow endpoint to populate the application, enabling Denise to apply immediately from Work4You without having to navigate to another site.
  • Denise clicks "Submit" after uploading her resume and answering all application questions.
  • The application is submitted to the Software Engineer, Req123 role.
  • Recruiters can see that Denise applied to Req123 and can review her resume, contact details, and all applicable action items.
  • Recruiters can also see Denise's application came from Work4You.

# Candidate Relationship Management Tools (CRM)

  • Sally Lee is a Recruiter at ABC Company and uses BLITZ, a candidate relationship management tool, to source and maintain relationships with candidates.
  • BLITZ already writes to CSODs Requisition Endpoints so Recruiters can see open positions in BLITZ without having to navigate to Cornerstone.
  • Sally is recruiting for their open Software Engineering position, Req123.
  • While looking at her engineering talent pool in BLITZ, Sally spots Jack, a very qualified candidate for Req123.
  • Rather than manually downloading Jack's resume and adding Jack to Req123 in Cornerstone, Sally clicks "Add Candidate to Requisition" in BLITZ and selects Req123.
  • BLITZ calls the POST Application and Candidate endpoint, and adds Jack and his resume to Cornerstone.
  • Sally returns to Cornerstone and sees that Jack has been added to Req123 and has an incomplete application.
  • Sally invites Jack to apply so he can finish the application and be considered for Req123.
    • Notes:
      • It will be up to the CRM (BLITZ in the above scenario) to determine at what point an applicant is added to the ATS and the POST Application and Candidate endpoint is called.
      • Endpoint will create a candidate if the candidate does not exist and will check if the candidate exists by their email.
      • If they do not exist, a new candidate and application will be created
      • If an application has already been started but not completed for the specific requisition, the POST Application and Candidate endpoint may be used to complete and or replace the existing application.

# Features

# Included Features

  • Application workflows with the following action items are supported:
    • Resume
    • Cover Letter
    • Additional Attachments
    • Pre-Screening Questions
    • Compliance Questions
    • Disclaimers
    • Notes
  • Posting a complete application
  • Posting an incomplete application
  • Creation of a candidate based on the posting of an application
  • Associating new applications with previously created accounts
  • Internal and external application workflows
  • Continue an existing application
  • Creates a new source in Cornerstone Admin Settings if a candidate is added via the API with a Source that does not yet exist
  • Apply with LinkedIn- If a vendor supports Apply with LinkedIn, when a candidate applies with their LinkedIn profile, a PDF is generated. This PDF should be passed as the applicant's Resume.

# Excluded Features

  • Getting a mobile friendly application workflow with a Custom Integration
  • Getting standard application workflow action items, such as:
    • LMS Forms
  • Getting application workflow action items with integrations, such as:
    • Edge integrations
    • SHL Legacy Integration
  • If an application is posted with a required Custom Integration, standard action item or integration, the application will be posted in an incomplete status
  • Resumes added via the POST Candidate and Application endpoint are not parsed
  • If an additional attachment is posted using the POST Candidate and Application endpoint, the entire additional attachment section will be considered complete, even if more than one additional attachment is marked required in the application workflow.

# API Consumer Requirements

  • An API consumer must know a requisition ID prior to requesting an application workflow, and creating a candidate or application. This can be found via the Get Job Requisition endpoint (information found here), a job distribution connector, or other source.
  • A 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.
  • If your applications, or your client's applications consist of more than a resume and cover letter, and frequently include prescreening questions, compliance questions or disclaimers, we recommend writing to our new POST Application and Candidate 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, and email, or as much as the full application without validating against the job requisition. It is up to the API consumer to validate against required application questions. We have no plans to deprecate the legacy Job Application API, as select vendors only post a resume and cover letter to Cornerstone.
  • While not required, API consumers may also call Cornerstone's Employee 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.