Developer API

# All requests require this header
x-api-key: cv_live_your_key_here

Authorization: Bearer cv_live_your_key_here

{
  "success": true,
  "count": 2,
  "parses_used": 12,
  "parses_limit": 100,
  "duplicates": [],
  "results": [
    {
      "file_index": 0,
      "filename": "john_doe.pdf",
      "success": true,
      "candidate": { /* full candidate object — see Response Schema */ },
      "parse_tier": "tier1",
      "cached": false
    }
  ]
}

{
  "success": true,
  "async": true,
  "job_id": "job_abc123",
  "status": "queued",
  "total": 25,
  "poll_url": "/api/portal/job_status/job_abc123",
  "results_url": "/api/portal/job_results/job_abc123",
  "parses_used": 12,
  "parses_limit": 100,
  "quota_status": "ok",
  "duplicates": []
}

curl https://cvault.tech/api/portal/job_status/job_abc123 \
  -H "x-api-key: cv_live_your_key_here"

{
  "success": true,
  "job_id": "job_abc123",
  "status": "processing",   // queued | processing | completed | failed
  "total": 25,
  "completed": 18,
  "failed": 0,
  "created_at": "2025-03-14T10:23:00Z",
  "updated_at": "2025-03-14T10:23:14Z"
}

curl "https://cvault.tech/api/portal/job_results/job_abc123?offset=0&limit=100" \
  -H "x-api-key: cv_live_your_key_here"

{
  "success": true,
  "job_id": "job_abc123",
  "total": 25,
  "offset": 0,
  "limit": 100,
  "results": [
    {
      "file_index": 0,
      "filename": "john_doe.pdf",
      "success": true,
      "candidate": { /* full candidate object */ },
      "parse_tier": "tier2",
      "cached": false
    },
    {
      "file_index": 1,
      "filename": "corrupt.pdf",
      "success": false,
      "error": "Could not extract text from file"
    }
  ]
}

curl -X POST https://cvault.tech/api/portal/extract_skills \
  -H "x-api-key: cv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "We are hiring a Senior Backend Engineer with Python, Django, PostgreSQL...",
    "title": "Senior Backend Engineer",
    "department": "Engineering"
  }'

{
  "success": true,
  "required": ["Python", "Django", "PostgreSQL", "REST APIs", "Docker"],
  "nice_to_have": ["Kubernetes", "Redis", "GraphQL", "AWS"]
}

curl -X POST https://cvault.tech/api/portal/rescore_candidates \
  -H "x-api-key: cv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job_abc123",
    "required_skills": ["Python", "Django", "PostgreSQL"],
    "nice_to_have_skills": ["Redis", "Kubernetes"]
  }'

{
  "success": true,
  "updated": 25,
  "scores": [
    {
      "candidate_id": "cand_xyz",
      "fit_score": 87,
      "hiring_recommendation": "strong_yes",
      "matched_skills": ["Python", "Django"],
      "missing_skills": ["PostgreSQL"]
    }
  ]
}

curl -X POST https://cvault.tech/api/portal/generate_interview_questions \
  -H "x-api-key: cv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cand_xyz",
    "job_context": "Senior backend role at a fintech startup, Python-heavy stack",
    "motivation_letter": "I am passionate about distributed systems..."
  }'

{
  "success": true,
  "generated_at": "2025-03-14T10:30:00Z",
  "questions": [
    {
      "category": "Technical",
      "question": "Walk me through how you would design a rate-limited API in Django.",
      "rationale": "Candidate claims Django expertise; role requires high-throughput API design."
    },
    {
      "category": "Behavioural",
      "question": "Tell me about a time you had to debug a production outage under pressure.",
      "rationale": "2-month gap in 2023 — probing for circumstances."
    }
  ]
}

# Create a webhook
curl -X POST https://cvault.tech/api/portal/webhooks \
  -H "x-api-key: cv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-app.com/webhooks/cvault",
    "event_types": ["parse.completed", "parse.failed"]
  }'

{
  "success": true,
  "webhook": {
    "id": "wh_123",
    "target_url": "https://your-app.com/webhooks/cvault",
    "event_types": ["parse.completed", "parse.failed"],
    "secret": "whsec_abc123..."
  }
}

import hmac, hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

// Node.js
const crypto = require('crypto');

function verifyWebhook(payloadBuffer, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payloadBuffer)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

{
  "error": "Monthly parse quota exhausted",
  "quota_used": 100,
  "quota_limit": 100,
  "resets_at": "2025-04-01T00:00:00Z"
}

{
  "title": "Senior Software Engineer",
  "company": "Acme Corp",
  "location": "London, UK",
  "start_date": "2021-03",
  "end_date": null,          // null = current position
  "is_current": true,
  "description": "Led backend team of 5, built real-time data pipeline...",
  "skills_used": ["Python", "Kafka", "PostgreSQL"]
}

{
  "degree": "BSc Computer Science",
  "institution": "University of Manchester",
  "location": "Manchester, UK",
  "start_date": "2014-09",
  "end_date": "2017-06",
  "grade": "First Class Honours"
}

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+44 7700 900123",
  "location": "London, UK",
  "linkedin": "https://linkedin.com/in/janesmith",
  "seniority": "senior",
  "total_experience_years": 8,
  "fit_score": 91,
  "hiring_recommendation": "strong_yes",
  "verdict": "Jane is an exceptionally strong candidate for this role...",
  "skills": ["Python", "Django", "PostgreSQL", "Docker", "Kubernetes"],
  "languages": [
    { "language": "English", "proficiency": "native" },
    { "language": "French", "proficiency": "professional" }
  ],
  "red_flags": [],
  "strengths": [
    "Deep Python expertise with 8 years production experience",
    "Direct experience in high-throughput fintech APIs"
  ],
  "experience": [
    {
      "title": "Senior Software Engineer",
      "company": "Acme Fintech",
      "start_date": "2021-03",
      "end_date": null,
      "is_current": true,
      "skills_used": ["Python", "Django", "PostgreSQL"]
    }
  ],
  "education": [
    {
      "degree": "BSc Computer Science",
      "institution": "University of Manchester",
      "end_date": "2017-06"
    }
  ]
}