API Documentation

Build powerful apprenticeship matching into your platform with the Job Verdict API

The Job Verdict API uses AI to analyze candidate profiles and job descriptions, providing intelligent matching scores and detailed explanations.

RESTful API

Simple HTTP requests with JSON responses

AI-Powered

Advanced matching with explainable scores

Production Ready

Webhooks, rate limits, and detailed logging

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Request Header

Authorization: Bearer jv_your_api_key_here

Keep your API keys secure

Never expose your API keys in client-side code or public repositories. Use environment variables or secure key management systems.

Quick Start

Make your first request

Send a POST request to analyze a candidate profile against a job description:

bash

curl -X POST https://www.jobverdict.com/api/b2b/apprenticeship-match \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateProfile": {
      "formations": [{
        "name": "BTS SIO",
        "level": "bac+2",
        "school": "Lycée Technique Paris",
        "year": 2023,
        "status": "completed"
      }],
      "skills": ["Python", "JavaScript", "React", "SQL"],
      "experiences": [{
        "company": "Tech Startup",
        "role": "Stagiaire développeur",
        "startDate": "06/2023",
        "endDate": "08/2023"
      }]
    },
    "jobDescription": "Recherche apprenti développeur full-stack pour rejoindre notre équipe...",
    "jobTitle": "Apprenti Développeur Full-Stack",
    "company": "TechCorp"
  }'

Response

json

{
  "matchScore": 85,
  "verdict": "GO",
  "scoreBreakdown": {
    "formation": {
      "raw": 90,
      "weighted": 36,
      "weight": 40
    },
    "contractType": {
      "raw": 100,
      "weighted": 25,
      "weight": 25
    },
    "experienceRedFlags": {
      "raw": 100,
      "weighted": 15,
      "weight": 15
    },
    "skills": {
      "raw": 75,
      "weighted": 15,
      "weight": 20
    }
  },
  "reasoning": "Excellent match: BTS SIO aligns perfectly with the position...",
  "meta": {
    "tokensUsed": 1250,
    "apiVersion": "1.0",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "modelVersion": "gpt-4o-mini-2024-07-18",
    "scoringVersion": "v1-a3f8c9d2e1b0"
  }
}

API Endpoints

Apprenticeship Match

POST/api/b2b/apprenticeship-match

Analyze candidate profile against a job description and get a match score

Request Body

candidateProfileobjectrequired

Candidate information including formations, skills, and experiences

jobDescriptionstringrequired

Full job description text

jobTitlestringrequired

Job title

companystringoptional

Company name

Response Fields

matchScorenumber

Match score from 0 to 100

verdictstring

"GO", "NOGO", or "CONDITIONAL"

scoreBreakdownobject

Detailed breakdown of score components

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200

Success

Request completed successfully

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing API key

429

Rate Limit Exceeded

Too many requests, check Retry-After header

Error Response Format

json

{
  "error": "Rate limit exceeded",
  "details": "You have exceeded your daily quota",
  "retryAfter": 3600
}

Rate Limits

API requests are limited by daily and monthly quotas based on your plan.

Daily Limit

1,000

requests per day

Monthly Limit

30,000

requests per month

Rate Limit Headers

bash

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1640000000
Retry-After: 3600

Monitor your usage

Track your API usage in real-time from your dashboard