candidate_shortlist_score

Score up to 100 supplied candidate profiles against one job profile with auditable matched requirements, gaps and confidence; no hiring decision is emitted.

When to use

Use after extracting multiple candidate profiles when an agent needs transparent batch comparison against one job.

Selection guidance

Role: specialized. Use after extracting multiple candidate profiles when an agent needs transparent batch comparison against one job.

Use cases

• candidate shortlist
• batch CV ranking
• recruitment screening

Access

• REST: POST https://api.rafidsystem.com/api/v1/recruitment/candidate-shortlist-score
• x402: POST https://api.rafidsystem.com/api/v1/x402/recruitment/candidate-shortlist-score
• MCP tool: candidate_shortlist_score

Price: $0.10 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.

Related tools

• cv_job_match
• extract_candidate_profile
• cv_improve
• generate_job_profile

Example input

{
  "job_profile": {
    "required_skills": [
      {
        "skill": "Python"
      }
    ],
    "required_experience_years": 2
  },
  "candidates": [
    {
      "candidate_id": "CAND-001",
      "candidate_profile": {
        "skills": [
          {
            "name": "Python"
          }
        ],
        "total_experience_years": 4
      }
    }
  ],
  "max_candidates": 100
}

Example output

{
  "job": {
    "required_skills": [
      {
        "skill": "Python"
      }
    ],
    "required_experience_years": 2
  },
  "candidates": [
    {
      "candidate_id": "CAND-001",
      "match_score": 80,
      "decision_support": {},
      "category_scores": {},
      "skill_match": [],
      "experience_analysis": {},
      "transferable_skills": [],
      "gaps": [],
      "risk_flags": [],
      "confidence": 0.7,
      "explanation": "Score is based on normalized job-relevant skills and supplied experience evidence only."
    }
  ],
  "scoring_methodology": {
    "weights": {
      "required_skills": 50,
      "experience": 30,
      "evidence": 20
    },
    "protected_attributes": "Ignored; never used for scoring or ranking."
  }
}

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "job_profile": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "candidates": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "candidate_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "candidate_profile": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          }
        },
        "required": [
          "candidate_id",
          "candidate_profile"
        ],
        "additionalProperties": false
      }
    },
    "max_candidates": {
      "default": 100,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "job_profile",
    "candidates",
    "max_candidates"
  ],
  "additionalProperties": false
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "job": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "scoring_methodology": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "job",
    "candidates",
    "scoring_methodology"
  ],
  "additionalProperties": false
}

Category: Recruitment Intelligence · hierarchy: specialized · idempotent: yes · side effects: no