Skip to content

Candidate API Documentation

Introduction

The Candidate API provides a suite of tools to manage candidate information, assignments, and interactions within the system. This API ensures efficient handling of candidate data while maintaining the integrity and security of operations.

Available Actions

The Candidate API supports the following key actions:

  1. Creating a Candidate: Add a new candidate to the system with all relevant details such as personal information and contact data.
  2. Recruiter Assignment: Manage the assignment of recruiters to candidates, including claiming and relinquishing relationships.
  3. Notes Management: Add, update, or retrieve notes associated with a candidate to capture important details and interactions.
  4. History Retrieval: Access the historical record of actions and changes related to a candidate, providing a comprehensive timeline of interactions.

Each action is designed to ensure a seamless and user-friendly experience for managing candidate records.

Recruiter Assignment

Introduction

The Recruiter Assignment API facilitates the assignment of recruiters to candidates within the system. This process ensures that recruiters can only engage with candidates explicitly assigned to them, preventing overlap or conflicts. The API provides functionality for both claiming a candidate and relinquishing an assignment.

Key Concepts

  • Claiming a Candidate: Recruiters can claim candidates who have not been previously assigned.
  • Relinquishing an Assignment: Recruiters can release their assignment from a candidate, making the candidate available for reassignment.

These actions ensure that candidate-recruiter relationships remain organized and streamlined.

Workflow

  1. Eligibility Check: The system verifies that the candidate is unassigned before allowing a recruiter to claim them.
  2. Claim Action: A recruiter claims an unassigned candidate, thereby establishing an exclusive relationship.
  3. Relinquish Action: If the recruiter no longer needs to work with the candidate, they can relinquish their assignment, freeing the candidate for others to claim.

General Rules

  • Unassigned Candidates Only: Only candidates without an existing recruiter assignment can be claimed.
  • Controlled Access: Actions to claim or relinquish candidates require proper authentication and authorization.

Claiming a Candidate

The claim operation allows a recruiter to take ownership of a candidate. This action is irreversible unless explicitly relinquished by the recruiter.

Conditions

  • Eligibility: The candidate must not already be assigned.
  • Purpose: To establish an exclusive relationship between a recruiter and a candidate.

Expected Outcome

Upon successful claim: - The recruiter is marked as the candidate's owner. - The candidate is no longer available for other recruiters to claim.

Relinquishing a Candidate

The relinquish operation allows a recruiter to release their assignment from a candidate. This action is used when a recruiter is no longer actively working with the candidate.

Conditions

  • Eligibility: Only candidates currently assigned to the recruiter performing the operation can be relinquished.
  • Purpose: To free up the candidate for reassignment to another recruiter.

Expected Outcome

Upon successful relinquishment: - The recruiter is removed as the candidate's owner. - The candidate becomes available for claiming by other recruiters.

This documentation outlines the conceptual framework for the Candidate API. For details about specific endpoints and data models, refer to the API specification.