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

```json
{
  "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

```json
{
  "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

```json
{
  "_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

```json
{
  "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

```json
{
  "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:

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

#### Response

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

### Delete a Candidate

```
DELETE /api/candidates/:id
```

Deletes a specific candidate.

#### Response

```json
{
  "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

```json
{
  "candidateId": "1234567890"
}
```

#### Response

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "confirm": true
}
```