candidate-portal-2/docs/API.md

API Documentation

This document provides information about the available API endpoints in the Candidate Filter Portal.

Authentication

Login

POST /api/auth/signin

Login using credentials or OAuth providers configured with NextAuth.

Logout

GET /api/auth/signout

Log out the current user.

Register

POST /api/register

Register a new user.

Request Body

{
  "name": "User Name",
  "email": "user@example.com",
  "password": "password123"
}

Candidates

Get All Candidates

GET /api/candidates

Retrieves a list of candidates with pagination and optional filtering.

Query Parameters

• page: Page number (default: 1)
• limit: Number of records per page (default: 50)
• status: Filter by status ('Active', 'Hold', 'Inactive')
• technology: Filter by technology
• visaStatus: Filter by visa status
• openToRelocate: Filter by relocation preference (true/false)
• currentStatus: Filter by current status
• search: Search by name, email, or technology

Response

{
  "candidates": [
    {
      "_id": "1234567890",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "123-456-7890",
      "technology": "React, Node.js",
      "visaStatus": "H1B",
      "location": "New York, NY",
      "openToRelocate": true,
      "experience": "5 years",
      "currentStatus": "In marketing",
      "status": "Active",
      "marketingStartDate": "2023-04-15T00:00:00.000Z",
      "dayRecruiter": "Jane Smith",
      "nightRecruiter": "Mike Johnson"
    },
    // ... more candidates
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Get a Single Candidate

GET /api/candidates/:id

Retrieves a specific candidate by ID.

Response

{
  "_id": "1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890",
  "technology": "React, Node.js",
  "visaStatus": "H1B",
  "location": "New York, NY",
  "openToRelocate": true,
  "experience": "5 years",
  "currentStatus": "In marketing",
  "status": "Active",
  "marketingStartDate": "2023-04-15T00:00:00.000Z",
  "dayRecruiter": "Jane Smith",
  "nightRecruiter": "Mike Johnson",
  "education": [
    {
      "degree": "BS",
      "field": "Computer Science",
      "university": "Stanford University",
      "yearCompleted": "2018"
    }
  ],
  "skills": ["JavaScript", "React", "Node.js", "MongoDB"],
  "interviewing": [
    {
      "company": "Google",
      "position": "Frontend Developer",
      "date": "2023-05-15T00:00:00.000Z",
      "status": "Scheduled",
      "feedback": ""
    }
  ],
  "assessment": [],
  "notes": "Excellent candidate with strong technical skills",
  "createdAt": "2023-04-10T00:00:00.000Z",
  "updatedAt": "2023-04-10T00:00:00.000Z"
}

Create a Candidate

POST /api/candidates

Creates a new candidate.

Request Body

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "phone": "123-456-7890",
  "visaStatus": "OPT",
  "location": "San Francisco, CA",
  "openToRelocate": true,
  "experience": "3 years",
  "technology": "React, Node.js",
  "bsYear": "2019",
  "msYear": "2021",
  "education": [
    {
      "degree": "BS",
      "field": "Computer Science",
      "university": "Stanford University",
      "yearCompleted": "2019"
    }
  ],
  "skills": ["JavaScript", "React", "Node.js"],
  "currentStatus": "In marketing",
  "status": "Active"
}

Response

{
  "message": "Candidate created successfully",
  "candidate": {
    "_id": "new_candidate_id",
    "name": "Jane Smith",
    // ... other fields
  }
}

Update a Candidate

PUT /api/candidates/:id

Updates a specific candidate.

Request Body

Partial update with only the fields that need to be changed:

{
  "location": "New York, NY",
  "openToRelocate": false,
  "technology": "React, Node.js, MongoDB"
}

Response

{
  "message": "Candidate updated successfully",
  "candidate": {
    "_id": "1234567890",
    "name": "Jane Smith",
    // ... updated fields
  }
}

Delete a Candidate

DELETE /api/candidates/:id

Deletes a specific candidate.

Response

{
  "message": "Candidate deleted successfully"
}

Hotlist

Get Hotlisted Candidates

GET /api/hotlist

Retrieves candidates that have been hotlisted, with pagination and optional filtering.

Query Parameters

Same as for GET /api/candidates.

Add to Hotlist

POST /api/hotlist

Adds a candidate to the hotlist.

Request Body

{
  "candidateId": "1234567890"
}

Response

{
  "message": "Candidate added to hotlist successfully",
  "candidate": {
    "_id": "1234567890",
    "name": "Jane Smith",
    // ... other fields
    "hotlisted": true
  }
}

Remove from Hotlist

DELETE /api/hotlist?candidateId=1234567890

Removes a candidate from the hotlist.

Response

{
  "message": "Candidate removed from hotlist successfully",
  "candidate": {
    "_id": "1234567890",
    "name": "Jane Smith",
    // ... other fields
    "hotlisted": false
  }
}

Reports

Get Reports Data

GET /api/reports

Retrieves data for generating reports.

Response

{
  "candidates": {
    "total": 100,
    "byStatus": {
      "Active": 75,
      "Hold": 15,
      "Inactive": 10
    },
    "byVisaStatus": {
      "H1B": 25,
      "OPT": 40,
      "Green Card": 20,
      "Citizen": 15
    },
    "byTechnology": {
      "React": 30,
      "Node.js": 25,
      "Angular": 20,
      "Python": 15,
      "Java": 10
    }
  }
}

Admin

Get All Users

GET /api/admin/users

Retrieves a list of users (admin only).

Create User

POST /api/admin/users

Creates a new user (admin only).

Update User

PUT /api/admin/users/:id

Updates a specific user (admin only).

Delete User

DELETE /api/admin/users/:id

Deletes a specific user (admin only).

Seed Database

POST /api/admin/seed

Seeds the database with demo data (admin only).

Purge Database

DELETE /api/admin/purge

Purges all data from the database (admin only).

Request Body

{
  "confirm": true
}