WHIZZHIRE
Docs · Quickstart

Job to shortlist in six calls.

Key → job → publish → screen → top-K with evidence → interview kit. JD generation and publishing are free; screening costs 1 credit per CV and kits cost 12 — free accounts start with 50 credits.

Get an API key#

Create a key at Dashboard → API Keys. The full key is displayed once at creation — only a SHA-256 hash is stored server-side, so copy it into your secret manager immediately.

shell
export HIRE_KEY="wz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Create a job#

Minimal inputs in, complete job post out: a free jd_generate run writes the description (English + Arabic here), SEO metadata, knockout questions, and a weighted screening rubric. The Idempotency-Key header makes retries safe — replays return the original job instead of creating a duplicate.

curl
curl -X POST https://hire.whizztech.ai/v1/jobs \
  -H "Authorization: Bearer $HIRE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fleet-ops-001" \
  -d '{
    "title": "Fleet Operations Manager",
    "seniority": "senior",
    "years_experience_min": 5,
    "location": "Dubai, UAE",
    "salary_min": 18000,
    "salary_max": 25000,
    "salary_currency": "AED",
    "skills": ["fleet management", "route optimization", "SAP"],
    "bilingual": true
  }'
Response · 202 Accepted
{
  "job": {
    "id": "4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18",
    "object": "job",
    "status": "draft",
    "slug": "fleet-operations-manager-9f2c1a",
    "title": "Fleet Operations Manager",
    "location": "Dubai, UAE",
    "seniority": "senior",
    "language": "en",
    "description_md": "",
    "rubric": {},
    "created_at": "2026-07-10T09:41:12.000Z"
  },
  "run_id": "0c9be9a4-2b77-4e19-8a5d-f21e6b40c7d3",
  "replayed": false
}

Wait for the run, publish#

Poll GET /v1/runs/{id} every couple of seconds, backing off toward 10s — or receive a webhook instead. Once the run succeeds, review or edit the generated JD and rubric, then publish. Publishing puts the job on your career page, Google for Jobs, and the board feeds — and enforces your plan's active-job limit (403 job_limit).

curl
curl https://hire.whizztech.ai/v1/runs/0c9be9a4-2b77-4e19-8a5d-f21e6b40c7d3 \
  -H "Authorization: Bearer $HIRE_KEY"

# once status is "succeeded":
curl -X POST https://hire.whizztech.ai/v1/jobs/4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18/publish \
  -H "Authorization: Bearer $HIRE_KEY"
Publish response · 200 OK (abridged)
{
  "job": {
    "id": "4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18",
    "object": "job",
    "status": "published",
    "published_at": "2026-07-10T09:46:20.000Z",
    "description_md": "## About the role\n\n…",
    "description_ar_md": "## عن الوظيفة\n\n…",
    "rubric": {
      "criteria": [
        { "id": "fleet", "name": "Fleet management experience", "weight": 5 },
        { "id": "systems", "name": "Systems (SAP/TMS)", "weight": 3 },
        { "id": "leadership", "name": "Team leadership", "weight": 2 }
      ]
    }
  },
  "run_id": "77a3f1c2-4b58-4e06-9d21-c85b90e4a7d3"
}

Screen every CV#

This is the call that costs credits: 1 per CV (deep mode: 3), debited up front and refunded automatically if the run fails. Every application with a CV is parsed, anonymized, scored against the rubric, and ranked; k controls how many candidates are flagged in_top_k. No applications yet? Bulk-import CVs first with POST /v1/cvs— it's free.

curl
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" \
  -d '{ "k": 5 }'
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
}

Get the top-K with evidence#

Results are ranked best-first. Every score comes with per-criterion reasoning and verbatim quotes from the CV — valid: truemeans the quote was matched against the actual CV text, so fabricated evidence can't masquerade as real.

curl
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",
  "status": "succeeded",
  "k": 5,
  "total_candidates": 87,
  "screened_count": 87,
  "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": "Managed a 140-vehicle fleet across 3 emirates for 4 years."
        }
      ],
      "evidence": [
        {
          "criterionId": "fleet",
          "quote": "Oversaw daily operations of a 140-vehicle mixed fleet across Dubai, Sharjah and Abu Dhabi",
          "page": 1,
          "valid": true
        }
      ]
    }
  ]
}

Generate an interview kit#

12 credits per kit: a 30-minute structured plan with six question categories, model answers, scoring rubrics, red flags — and probesthat pressure-test specific claims quoted from this candidate's CV.

curl
curl -X POST https://hire.whizztech.ai/v1/applications/e2c81f47-0a95-4d36-b8e1-6f24a0d7c593/interview-kit \
  -H "Authorization: Bearer $HIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# wait for run, then:
curl https://hire.whizztech.ai/v1/interview-kits/c7e2a940-8b13-4f6d-95a1-2d80e4b7c358 \
  -H "Authorization: Bearer $HIRE_KEY"
Kit · 200 OK (abridged)
{
  "id": "c7e2a940-8b13-4f6d-95a1-2d80e4b7c358",
  "object": "interview_kit",
  "status": "ready",
  "language": "en",
  "content": {
    "durationMinutes": 30,
    "plan": [
      { "minutes": 5, "section": "easy" },
      { "minutes": 10, "section": "cv_based" },
      { "minutes": 10, "section": "scenario" },
      { "minutes": 5, "section": "hard" }
    ],
    "sections": {
      "cv_based": [
        {
          "question": "You list a 140-vehicle fleet across three emirates — walk me through the telematics stack you ran it on.",
          "modelAnswer": "Names a concrete TMS/telematics platform, alert thresholds, …",
          "rubric": "5: specific systems + trade-offs; 3: names tools; 1: generic",
          "redFlags": ["Cannot name any system", "Claims sole credit for team outcomes"]
        }
      ]
    },
    "probes": [
      {
        "cvClaim": "Reduced fleet downtime by 35%",
        "quote": "reduced unplanned downtime by 35% year-over-year",
        "question": "35% from what baseline, measured how, and over what period?"
      }
    ]
  }
}

The same flow with the SDK#

The TypeScript SDK wraps all of the above — typed wire format, automatic retries, and runs.waitFor with backoff built in:

Node 18+ · @whizz/hire
import { WhizzHire } from "@whizz/hire";

const hire = new WhizzHire({ apiKey: process.env.HIRE_KEY! });

// job → publish
const ack = await hire.jobs.create(
  { title: "Fleet Operations Manager", seniority: "senior", location: "Dubai, UAE", bilingual: true },
  { idempotencyKey: "fleet-ops-001" },
);
await hire.runs.waitFor(ack.run_id!, { onProgress: (r) => console.log(r.stage) });
await hire.jobs.publish(ack.job.id);

// screen → top-K with evidence
const screen = await hire.jobs.screen(ack.job.id, { k: 5 });
await hire.runs.waitFor(screen.run_id);
const screening = await hire.screenings.get(screen.screening_id, { include: "results" });
const top = screening.results!.filter((r) => r.in_top_k);

// interview kit for the front-runner
const kitAck = await hire.applications.interviewKit(top[0].application_id);
await hire.runs.waitFor(kitAck.run_id);
const kit = await hire.interviewKits.get(kitAck.kit_id);
NextAuthentication→