---
title: "AI-powered candidate screening and ranking for recruiters, hiring managers, ATS providers and recruitment AI agents. Ing"
method: POST
path: "/api/v1/call/candidate_screening_ranking"
tags: ["expertise"]
---

# AI-powered candidate screening and ranking for recruiters, hiring managers, ATS providers and recruitment AI agents. Ing

`POST /api/v1/call/candidate_screening_ranking`

## Request

- Base URL: `https://mcp.gapup.io`
- URL: `https://mcp.gapup.io/api/v1/call/candidate_screening_ranking`
- Auth: HTTP bearer

AI-powered candidate screening and ranking for recruiters, hiring managers, ATS providers and recruitment AI agents. Ingests a job description and 1-50 candidate resumes, returning a ranked shortlist with score breakdowns across five weighted criteria: skills_match (tech stack and soft skills extracted from JD vs resume), experience_match (years vs seniority level inferred from JD), education_match (degree level + top-school detection), role_progression (Junior to Senior to Lead patterns), culture_fit_estimate (remote/hybrid, startup vs enterprise). Per candidate: overall_score 0-100, matched/missing skills, red_flags (job hopping, employment gaps, seniority mismatch), green_flags (long tenure, promotions), 3-5 interview questions, fit_summary. Diversity signals are first-name proxies ONLY with mandatory ethical WARNING. All processing is local -- no external API calls, instant response, privacy-preserving.

## Request body

- object
  - `job_description` string, required: Full text or summary of the job description and role requirements.
  - `candidates` object[], required: Array of candidate objects. Maximum 50.
    - `id` string, required: Unique identifier for this candidate.
    - `name` string: Optional full name (used for diversity signals).
    - `resume_text` string, required: Raw resume or CV text.
    - `linkedin_url` string: Optional LinkedIn URL (informational, not fetched).
    - `years_experience` number: Optional self-reported years of total experience.
  - `criteria_weights` object: Optional weighting per criterion. Default: skills=0.4, experience=0.2, education=0.1, progression=0.15, culture=0.15.
    - `skills_match` number
    - `experience_match` number
    - `education_match` number
    - `role_progression` number
    - `culture_fit` number
  - `role_country` string: Optional ISO 2-letter country code for regional context (informational).
  - `async` boolean: If true, returns a job_id immediately (<200ms) instead of waiting for the result. Poll the result with job_result(job_id). Use for slow tools to avoid client timeouts.

## Response `200`

Tool result

- object
  - `tool` string
  - `result` object
    - `job_description_summary` string, required
    - `required_skills` string[], required
    - `nice_to_have` string[], required
    - `candidates_ranked` object[], required
      - `id` string, required
      - `name` string
      - `overall_score` number, required
      - `score_breakdown` object, required
        - `skills_match` number, required
        - `experience_match` number, required
        - `education_match` number, required
        - `role_progression` number, required
        - `culture_fit_estimate` number, required
      - `matched_skills` string[], required
      - `missing_skills` string[], required
      - `red_flags` string[], required
      - `green_flags` string[], required
      - `recommended_interview_questions` string[], required
      - `fit_summary` string, required
    - `shortlist_recommended` string[], required
    - `diversity_signals` object
      - `inferred_gender_balance_pct` number
      - `risk_bias_alerts` string[], required
    - `sources` object[], required
      - `name` string, required
      - `url` string, required
      - `status` 'retrieved' | 'partial' | 'unavailable', required
    - `quality_score` number, required
    - `status` 'partial' | 'final' | 'failed', required
  - `request_id` string
  - `source` 'rest-api'
  - `ms` number

## Other responses

- `400`: Invalid arguments
- `401`: Unauthorized
- `402`: Payment Required — pay via x402 (USDC on Base) then retry with X-Payment header
- `404`: Tool not found
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api.md) · [All operations](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/revisions/afb9da3b98f4?raw)