---
title: "Handle Bench Preview"
method: POST
path: "/api/forms/bench-preview"
tags: ["Forms"]
---

# Handle Bench Preview

`POST /api/forms/bench-preview`

## Request

- Base URL: `https://api.ruzora.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ruzora.com/api/forms/bench-preview`
- Auth: none declared

Read-only pre-gate bench preview (Sol homepage hero, PRD §5.1b).

Runs the SAME matching as ``/shortlist-request`` — role → atoms, one
resolved skill request, the strict vetted filter, the ranker, the blind
``serialize_cards`` allowlist — and returns::

    {"status": "ready" | "preview" | "sourcing",
     "match_count": int,            # vetted_matching_required
     "cards": [...at most 3 blind cards...]}

``cards`` is the SAME shape as ``shortlist_candidates`` on the intake
response, so www renders both through one component.

What this endpoint does NOT do, by contract: no lead, no publish, no
magic-link token, no Slack, no email, no exposure-log row — no write of
any kind. Public and anonymous, so it carries its own per-IP limit on
top of the chat-api session limits. Sol calls it once, only after role +
stack are known; the model never learns bench numbers any other way.

## Request body

- BenchPreviewRequest: Body of ``POST /api/forms/bench-preview`` (Sol hero, PRD §5.1b FR-4b). The pre-gate slice of ``ShortlistRequestCreate``: role + stack, nothing identity-bearing. ``skills`` is a list because that is what the tool schema sends; the matching path accepts either form. ``engineers`` and ``timezone_overlap`` are accepted so the tool and intake schemas stay one shape; neither drives matching today (nor does it in the intake). Bounds are tight on purpose — this is anonymous and rate-limited, and every field reaches a SQL bind or a log line.
  - `role` string, required
  - `role_slug` string, nullable
  - `seniority` string, nullable
  - `skills` string[], required
  - `engineers` integer, nullable
  - `timezone_overlap` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api.md) · [All operations](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api/revisions/f9b8223f3ac4?raw)