API Integration Guide

basic+Match a CV against multiple jobs

curl -X POST https://api.jobzen.io/api/v1/match \
  -H "X-JobZen-Key: SBX_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cv_text": "Alice Martin, 5 ans Python, FastAPI, PostgreSQL...",
    "job_listings": [
      { "job_id": "job_001", "title": "Backend Engineer", "description": "Python, FastAPI, PostgreSQL requis..." },
      { "job_id": "job_002", "title": "Data Engineer", "description": "Python, Spark, Airflow..." }
    ],
    "options": { "explain": true }
  }'

// Response
{
  "cv_input_used": "cv_text",
  "matches": [
    {
      "job_id": "job_001",
      "title": "Backend Engineer",
      "score": 87,
      "strengths": ["Python expert", "FastAPI production experience"],
      "gaps": ["No Kubernetes experience"]
    },
    {
      "job_id": "job_002",
      "title": "Data Engineer",
      "score": 64,
      "strengths": ["Python"],
      "gaps": ["Spark", "Airflow"]
    }
  ],
  "usage": { "tokens": 312, "latency_ms": 340 }
}

basic+RecommendedFast call with stored profile (recommended for registered candidates)

# 1. Check that the candidate's profile is ready
curl https://api.jobzen.io/api/v1/candidates/YOUR_CANDIDATE_ID/profile \
  -H "X-JobZen-Key: your_key"

// Response when ready
{
  "ref": "YOUR_CANDIDATE_ID",
  "active": true,
  "has_profile": true,
  "linked_at": "2026-03-30T10:00:00Z",
  "profile": {
    "skills": ["Python", "FastAPI", "React"],
    "relevant_job_titles": ["Développeur Full Stack"],
    "profile_summary": "..."
  }
}

# 2. Call /match without re-sending the CV — ~40x faster
curl -X POST https://api.jobzen.io/api/v1/match \
  -H "X-JobZen-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_ref": "YOUR_CANDIDATE_ID",
    "job_listings": [
      { "job_id": "job_001", "title": "Backend Engineer", "description": "Python, FastAPI..." }
    ]
  }'

// cv_input_used = "stored_profile" confirms the fast path was used
// tokens: 0 = no LLM extraction cost
{
  "cv_input_used": "stored_profile",
  "matches": [{ "job_id": "job_001", "score": 87 }],
  "usage": { "tokens": 0, "latency_ms": 82 }
}

standard+Analyse a CV (profile extraction)

curl -X POST https://api.jobzen.io/api/v1/analyze \
  -H "X-JobZen-Key: SBX_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cv_pdf_base64": "<base64_encoded_pdf>",
    "candidate_ref": "cand_42"
  }'

// Response
{
  "cv_input_used": "cv_pdf_base64",
  "candidate_ref": "cand_42",
  "profile": {
    "skills": ["Python", "FastAPI", "PostgreSQL", "Docker"],
    "positions": ["Backend Engineer", "Senior Python Developer"],
    "languages": ["fr", "en"],
    "salary_range": { "min": 45000, "max": 65000, "currency": "EUR" },
    "sectors": ["tech", "saas"],
    "profile_summary": "Senior backend engineer with 7 years of experience in Python and cloud-native stacks."
  },
  "usage": { "tokens": 680, "latency_ms": 1840 }
}

standard+Score a profile against a job

curl -X POST https://api.jobzen.io/api/v1/score \
  -H "X-JobZen-Key: SBX_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_json": { "skills": ["Python", "FastAPI"], "positions": ["Backend Engineer"] },
    "job": {
      "title": "Lead Backend Engineer",
      "description": "Python 5y+, Kubernetes, architecture microservices...",
      "requirements": "Python expert, Kubernetes, CI/CD"
    },
    "options": { "structured": true }
  }'

// Response
{
  "score": 74,
  "strengths": ["Python expert (5y)", "FastAPI production experience"],
  "gaps": ["No Kubernetes experience", "Missing CI/CD detail"],
  "recommendation": "match_with_gaps",
  "usage": { "tokens": 210, "latency_ms": 1420 }
}

basic+RecommendedFast score with stored profile (recommended for registered candidates)

# Score with stored profile — no CV re-upload needed
curl -X POST https://api.jobzen.io/api/v1/score \
  -H "X-JobZen-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_ref": "YOUR_CANDIDATE_ID",
    "job": {
      "title": "Lead Backend Engineer",
      "description": "Python 5y+, Kubernetes, architecture microservices...",
      "requirements": "Python expert, Kubernetes, CI/CD"
    },
    "options": { "structured": true }
  }'

// profile resolved from platform via candidate_ref — no CV re-upload needed
// no CV extraction LLM cost; scoring LLM still applies
{
  "score": 74,
  "strengths": ["Python expert (5y)", "FastAPI production experience"],
  "gaps": ["No Kubernetes experience", "Missing CI/CD detail"],
  "recommendation": "match_with_gaps",
  "usage": { "tokens": 210, "latency_ms": 76 }
}

premium+Personalised CV coaching (improvement suggestions)

curl -X POST https://api.jobzen.io/api/v1/coach \
  -H "X-JobZen-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cv_text": "Junior Developer, 2 ans, JavaScript, React, HTML/CSS. Agence web.",
    "job": {
      "title": "Full-Stack Engineer",
      "description": "Startup SaaS B2B — React, Node.js, PostgreSQL, CI/CD.",
      "requirements": "2+ ans, Node.js, React, PostgreSQL, REST API, tests unitaires"
    },
    "candidate_ref": "dev-junior-001"
  }'

// Response
{
  "cv_input_used": "cv_text",
  "candidate_ref": "dev-junior-001",
  "suggestions": [
    {
      "category": "skills",
      "priority": "high",
      "suggestion": "Add Node.js and PostgreSQL — they are explicitly required and currently absent.",
      "rationale": "ATS will filter out the CV before a human sees it."
    },
    {
      "category": "experience",
      "priority": "medium",
      "suggestion": "Quantify one agency project: stack, team size, and outcome.",
      "rationale": "Startups compare candidates on impact, not just tools."
    },
    {
      "category": "presentation",
      "priority": "low",
      "suggestion": "Reframe 'Web Agency' as 'client SaaS products' if applicable.",
      "rationale": "SaaS B2B context is closer to the target role's environment."
    }
  ],
  "keywords_to_add": ["Node.js", "PostgreSQL", "REST API", "CI/CD", "unit tests"],
  "cv_sections": [
    {
      "section": "summary",
      "issue": "Too generic — no backend or full-stack signal.",
      "rewrite": "Full-stack developer (React + Node.js) with 2 years building web products. Eager to join a product-focused SaaS team."
    },
    {
      "section": "skills",
      "issue": "Missing backend technologies required by the role.",
      "rewrite": "Add: Node.js, PostgreSQL, REST APIs. Prioritise tech skills over tools (Figma, Trello)."
    }
  ],
  "ats_fit": {
    "score": 48,
    "blockers": ["Missing: Node.js", "Missing: PostgreSQL", "No CI/CD mention"]
  },
  "usage": { "tokens": 680, "latency_ms": 3200 }
}

Also accepts as CV source: cv_pdf_base64, cv_url, profile_json or candidate_ref.