Developer Documentation

CVSense API v1

Integrate CVSense® Evidence-Based Skill Validation into your ATS. Screen CVs, receive scored shortlists, and manage candidates via REST API.

Authentication Rate Limits Account Jobs Screening Candidates Shortlists Webhooks

Authentication

All requests require a Bearer token. Generate your key from the Developer Dashboard (Enterprise plan required).

Authorization: Bearer cvs_YOUR_API_KEY
Content-Type: application/json

Base URL: https://backend.cvsense.co.uk/api/v1

Rate Limits

120 requests per minute per API key. Headers returned: X-RateLimit-Limit, X-RateLimit-Remaining. Exceeding returns HTTP 429.

Account

GET/account— Get account info and plan

{
  "success": true,
  "data": {
    "id": 19,
    "email": "you@company.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "plan": {
      "plan_key": "recruiter_enterprise",
      "plan_name": "Enterprise",
      "job_posting_limit": null,
      "application_limit_per_job": null,
      "credit_limit": 500
    }
  }
}

GET/account/credits— Get credit balance

GET/account/usage— Get last 50 credit transactions

Jobs

GET/jobs— List jobs (paginated, max 100 per page)

POST/jobs— Create a job

Request Body

{
  "title": "Software Engineer",         // required, max 255
  "description": "<p>Looking for...</p>", // required
  "location": "London, UK",              // required, max 255
  "employment_type": "full-time",        // full-time|part-time|contract|temporary|internship
  "working_method": "hybrid",            // in-house|hybrid|remote
  "salary_min": 50000,
  "salary_max": 70000,
  "salary_currency": "GBP",
  "salary_period": "year",               // year|month|week|day|hour
  "max_applications": 500                // default: 1000
}

GET/jobs/{id}— Get job details

PUT/jobs/{id}— Update a job

DELETE/jobs/{id}— Delete a job

GET/jobs/{id}/applications— Get applications for a job

Screening (EBSV)

Upload CVs against a job description. Each CV costs 1 credit. Results include AI analysis summary, strengths, weaknesses, and tri-state skill classification.

POST/screening/batch— Create a screening batch

Request

{
  "job_title": "Software Engineer",
  "job_description": "We are looking for...",
  "job_requirements": "5+ years Laravel, Vue.js..."
}

POST/screening/batch/{batchId}/upload— Upload CVs (multipart/form-data, max 50 files, PDF/DOCX)

POST/screening/batch/{batchId}/start— Start AI screening

GET/screening/batch/{batchId}/status— Poll status (call every 5-10s)

Status Response

{
  "success": true,
  "data": {
    "status": "processing",
    "total_files": 50,
    "processed_files": 23,
    "successful_files": 20,
    "failed_files": 3,
    "invalid_files": 2
  }
}

GET/screening/batch/{batchId}/results— Get scored ranked results

Results Response

{
  "success": true,
  "data": [{
    "id": "00106633-d87c-45cb-...",
    "candidate_name": "Rohit Parmar",
    "candidate_email": "rohit@example.com",
    "candidate_phone": "+44 7700 900000",
    "match_score": 65,
    "match_status": "strong",
    "summary": "Full Stack Developer with 6 years experience...",
    "strengths": [
      "Strong Laravel expertise validated by project evidence",
      "Proficient in Vue.js demonstrated by frontend work"
    ],
    "weaknesses": [
      "Lacks CI/CD and cloud platform experience",
      "No demonstrated AI/ML integration"
    ],
    "skills_found": {
      "validated": ["Laravel", "Vue.js", "JavaScript", "CSS", "Docker"],
      "missing": ["SQL", "AI/ML", "CI/CD", "Cloud platforms"],
      "nice_to_have": [],
      "validation_ratio": "5/9 required skills validated"
    },
    "experience_data": {
      "total_years": 6,
      "current_role": "Full Stack Developer",
      "relevant_years": 6
    },
    "education_data": {
      "degree": "B.E. Computer Science",
      "institution": "University of Mumbai"
    }
  }]
}

match_status values:

exceptional (85-100) · strong (65-84) · good (45-64) · fair (20-44) · limited (0-19) · invalid (unreadable CV)

GET/screening/batch/{batchId}/results/{itemId}— Get detailed report for one candidate

GET/screening/batch/{batchId}/report/{itemId}— Download PDF report (binary)

DELETE/screening/batch/{batchId}— Cancel batch (unprocessed credits refunded)

Candidates

GET/candidates— List candidates. Filter: ?job_id=X&status=shortlisted&per_page=50

GET/candidates/{id}— Get candidate detail

PATCH/candidates/{id}/status— Update status

Request

{ "status": "shortlisted" }

// Valid: new, reviewed, shortlisted, rejected, offered, hired

Shortlists

GET/shortlists— List shortlist projects

POST/shortlists— Create shortlist

Request

{ "title": "Q2 Senior Devs", "description": "..." }

GET/shortlists/{id}/candidates— Get candidates in shortlist

POST/shortlists/{id}/candidates— Add candidates (max 100)

Request

{
  "candidates": [
    { "name": "Jane Smith", "email": "jane@ex.com", "score": 92, "notes": "Strong" }
  ]
}

Webhooks

POST/webhooks— Register webhook

Request

{
  "url": "https://your-app.com/hook",
  "events": ["screening.completed", "job.application.received"]
}

// Events: screening.completed, screening.failed,
// candidate.scored, job.application.received,
// candidate.status.changed

GET/webhooks— List webhooks

DELETE/webhooks/{id}— Delete webhook

POST/webhooks/{id}/test— Send test ping

Signature Verification

const signature = req.headers['x-cvsense-signature'];
const expected = crypto.createHmac('sha256', secret)
  .update(JSON.stringify(req.body)).digest('hex');
if (signature !== expected) return res.status(401).end();

Retry policy: 3 attempts with exponential backoff (10s, 60s, 300s). Auto-disabled after 10 consecutive failures. Respond 2xx within 10s.

Ready to integrate?

Generate your API key from the Enterprise dashboard.

Get Started Contact Sales