# BRAINIAC Candidate Shortlist Ranker

> BRAINIAC Candidate Shortlist Ranker is a paid API for AI agents from www.brainiac.software, paid per call via x402, $0.05/call, status unknown (last checked 2026-11-17).

Scores and ranks a list of job candidates against structured job requirements, returning a transparent per-factor breakdown with points and explanations.

## Facts

- Endpoint: POST https://www.brainiac.software/api/v1/recruitment-operations/candidate-shortlist-rank?utm_source=zero.xyz
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-17
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/brainiac-candidate-shortlist-ranker-cb23ff0e
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_MS0r5vaRx9f94-Hw6wjLl

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability brainiac-candidate-shortlist-ranker-cb23ff0e -d '<json body>'
```

Example prompt: I have 5 candidates for a Backend Engineer role — can you rank them against these requirements: TypeScript (required, 3+ years), JavaScript (preferred), and a Bachelor's degree (required)? Here are their resumes and skill lists. Flag any inferred matches so I know where assumptions were made.

## When to prefer this

Choose this endpoint when you need a structured, transparent, factor-by-factor candidate ranking against explicit job requirements — especially when you need auditability (every point explained), alias-aware skill matching, and a strict no-invention guarantee. Prefer this over LLM free-form resume review when you need deterministic scoring, structured JSON output, and compliance-safe ranking that explicitly ignores protected attributes. Best suited for agentic recruitment pipelines that handle up to 20 candidates per call.

## Known failure modes

- Invalid or missing required fields (title, jobText, candidates, requirements) return a validation error
- Candidate array with zero items is rejected by minItems:1 constraint
- Exceeding maxItems limits (20 candidates, 40 skills, etc.) returns a schema error
- Ties in score preserve caller-supplied order and are flagged with a tie_order issue
- Dates with end before start are flagged as conflicts and not rewritten
- Skills or qualifications not present in the resume are scored 0 and never invented
- Payment failure via x402 returns a 402 response before any processing occurs

## How this service works

Pay-per-call APIs for AI agents: OFAC sanctions screening, compliance checks, token security, and Base chain data via x402. No account. Fixed USDC price. MCP-ready.

## Output

A JSON object containing: a ranked list of candidates with scores and rank positions, per-factor point breakdowns with explanations for every candidate-requirement pair, inferred match flags (where aliases resolved a skill name), detected data issues (e.g. date conflicts), and a fixed limitations disclaimer stating no hiring decision is made and protected attributes are ignored.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "title": {
   "type": "string",
   "maxLength": 200,
   "minLength": 1
  },
  "aliases": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "requirement",
     "candidate"
    ],
    "properties": {
     "candidate": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
     },
     "requirement": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
     }
    },
    "additionalProperties": false
   },
   "maxItems": 40
  },
  "jobText": {
   "type": "string",
   "maxLength": 20000,
   "minLength": 1
  },
  "candidates": {
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1
     },
     "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
     },
     "text": {
      "type": "string",
      "maxLength": 20000,
      "minLength": 1
     },
     "roles": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "title",
        "employer"
       ],
       "properties": {
        "end": {
         "type": "string",
         "maxLength": 20,
         "minLength": 1
        },
        "text": {
         "type": "string",
         "maxLength": 2000,
         "minLength": 1
        },
        "start": {
         "type": "string",
         "maxLength": 20,
         "minLength": 1
        },
        "title": {
         "type": "string",
         "maxLength": 200,
         "minLength": 1
        },
        "employer": {
         "type": "string",
         "maxLength": 200,
         "minLength": 1
        }
       },
       "additionalProperties": false
      },
      "maxItems": 20
     },
     "skills": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "name"
       ],
       "properties": {
        "name": {
         "type": "string",
         "maxLength": 200,
         "minLength": 1
        },
        "years": {
         "type": "number",
         "maximum": 80,
         "minimum": 0
        }
       },
       "additionalProperties": false
      },
      "maxItems": 40
     },
     "qualifications": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "name"
       ],
       "properties": {
        "name": {
         "type": "string",
         "maxLength": 200,
         "minLength": 1
        },
        "y
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "title": "Backend Engineer",
  "issues": [
   {
    "code": "end_before_start",
    "kind": "conflict",
    "field": "Analyst",
    "detail": "The end date is before the start date. The dates were not rewritten.",
    "candidateRef": "grace"
   },
   {
    "code": "tie_order",
    "kind": "ignored",
    "field": "rank",
    "detail": "Tied scores keep the caller's order. Name and personal attributes are not used to break a tie.",
    "candidateRef": ""
   }
  ],
  "status": "ranked",
  "factors": [
   {
    "name": "TypeScript",
    "detail": "The skill matches and the supplied 4 years meet 3.",
    "points": 2,
    "inferred": false,
    "candidateRef": "ada",
    "requirementId": "R1"
   },
   {
    "name": "JavaScript",
    "detail": "The caller alias maps JS to JavaScript. The resume does not contain JavaScript.",
    "points": 1,
    "inferred": true,
    "candidateRef": "ada",
    "requirementId": "R2"
   },
   "…"
  ],
  "checkedAt": "2026-11-03T10:00:00.000Z",
  "candidates": [
   {
    "tie": false,
    "rank": 1,
    "score": 5,
    "candidateRef": "ada"
   },
   {
    "tie": false,
    "rank": 2,
    "score": 0,
    "candidateRef": "grace"
   }
  ],
  "limitations": [
   "No hiring decision is made. A person decides.",
   "Skills, employment history, qualifications, and references are not invented.",
   "…"
  ],
  "hiringDecision": false,
  "qualificationsInvented": false
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/brainiac-candidate-shortlist-ranker-cb23ff0e/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from www.brainiac.software](https://www.zero.xyz/host/www.brainiac.software/llms.txt)
