WHIZZHIRE
Docs · API · Screening

Screening.

One call reads every CV on a job — PDF, DOCX, scanned, two-column, Arabic — scores each candidate against your weighted rubric, quotes its evidence verbatim from the CV, and ranks everyone with the top-K flagged. Humans make the final call; the AI never rejects.

Start a screening#

POST/v1/jobs/{id}/screen
FieldTypeDescription
kintegerdefault: 10How many top candidates to flag in_top_k (1–100). Purely a recommendation marker — every candidate is scored and ranked either way.
modeenumdefault: standardstandard = 1 credit/CV, evidence pass on the top slice · deep = 3 credits/CV, evidence pass on every CV.
Request
curl -X POST https://hire.whizztech.ai/v1/jobs/4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18/screen \
  -H "Authorization: Bearer $HIRE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fleet-ops-screen-1" \
  -d '{ "k": 5, "mode": "standard" }'
Response · 202 Accepted
{
  "object": "screening",
  "screening_id": "8a1c5e72-3f90-4b6d-a2e8-51c7d0b94f36",
  "run_id": "5b8f0d21-6a3e-4c97-b1d0-84e7f2a9c655",
  "k": 5,
  "mode": "standard",
  "candidates": 87,
  "credits_charged": 87,
  "replayed": false
}

Eligible = applications on the job that have a CV and are not withdrawn or rejected. Credits (candidates × 1, deep × 3) are debited up front and refunded automatically if the run fails. The job must have a rubric — 400 missing_rubric otherwise. Poll GET /v1/runs/{run_id} or subscribe to the screening.completed webhook.

Rubric & weights#

The rubric lives on the job (rubric.criteria, written by the JD composer and editable via PATCH /v1/jobs/{id}). Each criterion has an integer weight 1–10; at scoring time weights are normalized to fractions and the overall score is the weighted average of per-criterion scores (each 0–100):

Rubric → math
{
  "criteria": [
    { "id": "fleet",      "name": "Fleet management experience", "weight": 5 },
    { "id": "systems",    "name": "Systems (SAP/TMS)",           "weight": 3 },
    { "id": "leadership", "name": "Team leadership",             "weight": 2 }
  ]
}

// weights normalize to fractions: 5+3+2 = 10 → 0.5, 0.3, 0.2
// overall = 0.5×score(fleet) + 0.3×score(systems) + 0.2×score(leadership)

Anonymization before scoring#

Before any model sees a CV, personally identifying details — name, email, phone, photo, address — are stripped and stored separately. The scoring model reads only the anonymized text. Name removal is the one bias mitigation with measured near-complete effectiveness; prompt-level "be unbiased" instructions demonstrably are not. The identifying details rejoin the result only at display time, and the model versions used for each stage are recorded on the screening (model_versions) for audit.

Results#

GET/v1/screenings/{id}

Add ?include=results for the ranked list (best first):

Request
curl "https://hire.whizztech.ai/v1/screenings/8a1c5e72-3f90-4b6d-a2e8-51c7d0b94f36?include=results" \
  -H "Authorization: Bearer $HIRE_KEY"
Response · 200 OK (abridged)
{
  "id": "8a1c5e72-3f90-4b6d-a2e8-51c7d0b94f36",
  "object": "screening",
  "job_post_id": "4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18",
  "run_id": "5b8f0d21-6a3e-4c97-b1d0-84e7f2a9c655",
  "status": "succeeded",
  "k": 5,
  "mode": "standard",
  "rubric": { "criteria": [ … ] },
  "model_versions": { "parse": "…", "score": "…", "evidence": "…" },
  "total_candidates": 87,
  "screened_count": 87,
  "finished_at": "2026-07-10T10:12:44.000Z",
  "results": [
    {
      "application_id": "e2c81f47-0a95-4d36-b8e1-6f24a0d7c593",
      "candidate": { "id": "1b7d4e90-…", "full_name": "Omar Haddad" },
      "score": 86.5,
      "verdict": "strong",
      "rank": 1,
      "in_top_k": true,
      "criterion_scores": [
        {
          "criterionId": "fleet",
          "name": "Fleet management experience",
          "score": 92,
          "weight": 5,
          "reasoning": "4 years running a 140-vehicle mixed fleet across 3 emirates; owned maintenance scheduling and utilization KPIs."
        },
        {
          "criterionId": "systems",
          "name": "Systems (SAP/TMS)",
          "score": 78,
          "weight": 3,
          "reasoning": "Daily SAP PM usage; TMS exposure limited to one implementation project."
        }
      ],
      "evidence": [
        {
          "criterionId": "fleet",
          "quote": "Oversaw daily operations of a 140-vehicle mixed fleet across Dubai, Sharjah and Abu Dhabi",
          "page": 1,
          "valid": true
        }
      ],
      "red_flags": [],
      "missing_info": ["No certification dates listed"],
      "fraud_signals": []
    }
  ]
}
FieldTypeDescription
scorenumberWeighted 0–100 overall — the weighted average of criterion_scores.
criterion_scoresarray{criterionId, name, score 0–100, weight, reasoning} per rubric criterion. The visible math behind every ranking.
evidencearray{criterionId, quote, page, valid} — quotes are matched verbatim (whitespace-normalized) against the CV text. valid: true means the quote exists in the CV; unmatched quotes are flagged false, never silently presented as real.
verdictenumstrong · good · partial · weak — a tiered read of the overall score.
rank / in_top_kint / boolPosition in this screening (1 = best) and whether the candidate falls inside your chosen K.
red_flags / missing_infoarrayConcerns worth probing in interview, and information the CV simply doesn't state.
fraud_signalsarrayAI-flood defense: duplicate submissions, internal inconsistencies, boilerplate signals — evidence-checked, not "AI detection".

Human-in-the-loop#

Screening changes an application's status from new to screening — and nothing else. in_top_k is a recommendation; advancing or rejecting a candidate is a human action taken in the dashboard, recorded with the acting user, and flagged when it overrides the AI recommendation. Every scored, ranked, and dispositioned event lands in an immutable decision log (4-year retention) with the rubric snapshot and model versions — this is what NYC LL144, Colorado, California FEHA, and GDPR Art. 22 audits ask for.

NextInterview Kits→