Skip to main content

API Reference

LightningHire offers a comprehensive API for integrating the platform with your existing systems and workflows.

Authentication​

All API routes are protected using NextAuth.js. You must include a valid authentication token in the headers of your requests.

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`
};

API Endpoints​

Jobs​

GET
/api/jobs
List all jobs for the current user.Requires Authentication
POST
/api/jobs
Create a new job.Requires Authentication
GET
/api/jobs/:id
Get job details.Requires Authentication
PUT
/api/jobs/:id
Update job.Requires Authentication
DELETE
/api/jobs/:id
Delete job.Requires Authentication
POST
/api/jobs/bulk
Bulk import jobs.Requires Authentication

Candidates​

GET
/api/candidates
List all candidates.Requires Authentication
POST
/api/candidates
Create a new candidate.Requires Authentication
GET
/api/candidates/:id
Get candidate details.Requires Authentication
PUT
/api/candidates/:id
Update candidate.Requires Authentication
DELETE
/api/candidates/:id
Delete candidate.Requires Authentication
POST
/api/candidates/bulk
Bulk import candidates.Requires Authentication
POST
/api/candidates/parse
Parse resume data.Requires Authentication

Matching​

GET
/api/matching/:jobId
Get matches for a job.Requires Authentication
GET
/api/matching/job/:jobId/candidate/:candidateId
Get specific match details.Requires Authentication
POST
/api/matching/evaluate
Manually evaluate a match.Requires Authentication

Messages​

GET
/api/messages
Get all messages.Requires Authentication
GET
/api/messages/unread
Get unread messages count.Requires Authentication
PUT
/api/messages/:id/read
Mark message as read.Requires Authentication

Request Format​

All requests with a body should be sent as JSON:

const response = await fetch('/api/jobs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    title: 'Software Engineer',
    description: 'We are looking for a software engineer...',
    requirements: 'At least 3 years of experience...',
    skills: [
      { name: 'JavaScript', importance: 5 },
      { name: 'React', importance: 5 },
      { name: 'Node.js', importance: 4 }
    ]
  })
});

Response Format​

All API responses follow a consistent format:

For successful operations:

{
  "success": true,
  "data": { ... },
  "message": "Operation successful",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}

For errors:

{
  "success": false,
  "error": "Error type",
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}

Pagination​

List endpoints support pagination with query parameters:

/api/resource?page=1&limit=10&sort=createdAt&order=desc

Search and Filtering​

List endpoints support search and filtering:

/api/resource?search=keyword&filter[field]=value

Error Codes​

Error CodeHTTP StatusDescription
UNAUTHORIZED401Authentication required
FORBIDDEN403Not authorized to access the resource
NOT_FOUND404Resource not found
INVALID_ID400Invalid ID format
VALIDATION_ERROR400Input validation failed
SERVER_ERROR500Internal server error

Rate Limiting​

API requests are rate limited to 100 requests per minute per user. Exceeding this limit will result in a 429 Too Many Requests response.

Example API Usage​

This example shows how to fetch all jobs and create a new candidate:

// Fetch all jobs
async function getJobs() {
  const response = await fetch('/api/jobs', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const result = await response.json();
  
  if (!result.success) {
    throw new Error(result.message);
  }
  
  return result.data;
}

// Create a new candidate
async function createCandidate(candidateData) {
  const response = await fetch('/api/candidates', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify(candidateData)
  });
  
  const result = await response.json();
  
  if (!result.success) {
    throw new Error(result.message);
  }
  
  return result.data;
}