# Review a shortlist before a client call (/workflows/review-a-shortlist)

Your client wants their first go-to-market engineer. On the call they’ll ask who has built an outbound operation from scratch. Riley Okafor, Sam Lindqvist and Alex Marchetti made the shortlist. Here’s how you’d pick the people worth discussing in Kith ATS, and be ready to explain why.

If this is your first time using the API, [make your first request in a test workspace](/api#making-a-request). You can also [try this shortlist on Kith’s ATS page](https://www.kith.contact/ats#components).

## 1. Read the evidence for each person [#1-read-the-evidence-for-each-person]

Open the role and read what you have on each person before you answer. Each one leaves a question you still need to ask.

| Person | What you have | What to check |
| --- | --- | --- |
| Riley Okafor, Example Labs | Built the outbound stack alone at seed stage and turned it into a repeatable pipeline. | Who took over the campaigns once the system was running? |
| Sam Lindqvist, Sample Analytics | Writes the code and runs the campaigns. | Which parts did Sam build from scratch? |
| Alex Marchetti, Fictional Robotics | Built tooling for product-led growth. | Has Alex run outbound to people who had never tried the product? |

<Tabs items={["UI","API"]}>
<Tab value="UI">
The [review card](/ui/candidate-review-card) puts Riley’s evidence above the answer, so you read why before you decide.

<UiPreview slug="candidate-review-card" title="Riley’s evidence for this role" minHeight={420} />

```tsx
"use client";

import { useState } from "react";
import { PersonAvatar } from "@epicbagel/saas-kit/primitives/person-avatar";
import { CandidateClientDecision, CandidateGradeBadge, CandidateReviewCard } from "@recruiteros/recruit-ui/recruit";

// A fictional person at a fictional company.
export function ReviewCardExample() {
  const [answer, setAnswer] = useState<{ decision: "yes" | "no"; reason: string } | null>(null);

  return (
    <CandidateReviewCard
      name="Riley Okafor"
      headline="GTM Engineer · Example Labs"
      avatar={<PersonAvatar name="Riley Okafor" photoUrl="/people/riley-okafor.jpg" size={44} decorative />}
      // Pass their own banner as `cover`. Left out, the card draws the kit's stock one; `compact` caps it at 96px.
      coverSize="compact"
      // A cover is any media of yours. With no banner of their own, the kit's stock one, picked by name.
      facts={[
        { label: "Fit", value: <CandidateGradeBadge grade="A" label="Strong fit" /> },
        { label: "Location", value: "London" },
        { label: "Experience", value: "6 years" },
      ]}
      insight={{ label: "Why", value: "Built the outbound stack alone at a seed-stage company and took it to a repeatable pipeline." }}
      actions={
        <CandidateClientDecision
          candidateName="Riley Okafor"
          decision={answer?.decision}
          reason={answer?.reason}
          onDecide={async (decision, reason) => setAnswer({ decision, reason })}
        />
      }
    />
  );
}
```
</Tab>

<Tab value="API">
Read the role with `job` and filter its `candidates` to `SHORTLISTED`. `summary` holds up to four points of evidence for this job. Keep each `id` and `version`: an edit to that person’s application asks for both.

```graphql
query Shortlist($jobId: ID!) {
  job(id: $jobId) {
    title
    candidates(filter: { stages: [SHORTLISTED] }) {
      edges {
        node {
          id version stage grade nextAction
          summary { text sentiment }
          candidate { name currentTitle currentCompany photoUrl bannerUrl }
        }
      }
    }
  }
}
```
</Tab>
</Tabs>

To keep Riley’s question with the role, save it as the next action on Riley’s application with [`updateJobCandidateFollowUp`](/api/reference/mutations/update-job-candidate-follow-up). Pass the `id` and `version` you read.

## 2. Say Yes or No, and why [#2-say-yes-or-no-and-why]

Choose **Yes** for someone you want to discuss, or **No** to hold them back. Give a reason you could defend on the call. For Riley, that might be “Built the first outbound system alone, which is what this client needs.”

<Tabs items={["UI","API"]}>
<Tab value="UI">
Try the [longlist review block](/blocks/longlist-review). Answer for each person, then open **To review** to see who is left. The example keeps your answers until you reload the page.

<UiPreview slug="longlist-review" title="Yes or No for each person on the role" minHeight={640} />

```tsx
"use client";

import { useState } from "react";
import { PersonAvatar } from "@epicbagel/saas-kit/primitives/person-avatar";
import { Stack } from "@epicbagel/saas-kit/primitives/stack";
import { Text } from "@epicbagel/saas-kit/primitives/text";
import { CandidateClientDecision } from "@recruiteros/recruit-ui/recruit/candidate-client-decision";
import { CandidateFilterChips } from "@recruiteros/recruit-ui/recruit/candidate-filter-chips";
import { CandidateReviewCard } from "@recruiteros/recruit-ui/recruit/candidate-review-card";

const people = [
  { id: "riley", name: "Riley Okafor", title: "GTM Engineer · Example Labs", evidence: "Built the first outbound system and ran the campaigns.", photo: "/people/riley-okafor.jpg" },
  { id: "sam", name: "Sam Lindqvist", title: "RevOps Lead · Sample Analytics", evidence: "Runs weekly campaigns. Check which parts of the stack Sam built.", photo: "/people/sam-lindqvist.jpg" },
  { id: "alex", name: "Alex Marchetti", title: "Growth Engineer · Fictional Robotics", evidence: "Built product-led growth tooling. Cold outbound experience is still open.", photo: "/people/alex-marchetti.jpg" },
];

type Decision = { decision: "yes" | "no"; reason: string };
const filters = [{ value: "waiting", label: "To review" }, { value: "yes", label: "Yes" }, { value: "no", label: "No" }];

export function LonglistReviewBlock() {
  const [answers, setAnswers] = useState<Record<string, Decision>>({});
  const [filter, setFilter] = useState<string | null>(null);
  const status = (id: string) => answers[id]?.decision ?? "waiting";
  const visible = people.filter(person => !filter || status(person.id) === filter);
  return (
    <Stack gap="md">
      <Text weight="semibold">Founding GTM Engineer · Longlist review</Text>
      <CandidateFilterChips value={filter} onChange={setFilter} allLabel="Everyone"
        options={filters.map(item => ({ value: item.value, label: `${item.label} (${people.filter(person => status(person.id) === item.value).length})` }))} />
      {visible.length === 0 && <Text role="status">No candidates in this group.</Text>}
      {visible.map(person => (
        <CandidateReviewCard key={person.id} name={person.name} headline={person.title} coverSize="compact"
          avatar={<PersonAvatar name={person.name} photoUrl={person.photo} size={40} decorative />}
          insight={{ label: "Evidence for this role", value: person.evidence }}
          actions={<CandidateClientDecision candidateName={person.name}
            decision={answers[person.id]?.decision} reason={answers[person.id]?.reason}
            onDecide={async (decision, reason) => setAnswers(previous => ({ ...previous, [person.id]: { decision, reason } }))} />}
        />
      ))}
    </Stack>
  );
}
```
</Tab>

<Tab value="API">
Each person’s application holds the standing `decision`, its `decisionReason`, who decided and when. Filter by `decisions` to list the people you said Yes to.

```graphql
query PeopleToDiscuss($jobId: ID!) {
  job(id: $jobId) {
    candidates(filter: { decisions: [YES] }) {
      edges {
        node {
          id stage decision decisionReason decidedAt
          decidedBy { name }
          candidate { name }
        }
      }
    }
  }
}
```
</Tab>
</Tabs>

The API gives the decision and its reason for reading. To save a recruiter’s answer, connect the control’s `onDecide` to an authorised write in your own backend. Keep sample decisions in the browser until that write is available.

Riley is still **Shortlisted**. Your yes means “bring Riley up on the call.” Move the stage when the next step actually happens, such as the client booking an interview. [Run a job from intake to placement](/workflows/headless-ats) shows that move.

## 3. Decide what the client sees [#3-decide-what-the-client-sees]

For the call, you might share Riley’s name and the evidence about the outbound system. Keep the team’s decision reasons and follow-up questions in the desk view. Choose a separate action for sharing so a recruiter can record a candid reason without sending it to the client.

<Tabs items={["UI","API"]}>
<Tab value="UI">
The [presentation list block](/blocks/present-list) shows who the client has seen for this role, the note sent with each person and what the client said back.

<UiPreview slug="present-list" title="Who the client has seen for this role" minHeight={520} />

```tsx
"use client";

import { useState } from "react";
import { Button } from "@epicbagel/saas-kit/primitives/button";
import { PersonAvatar } from "@epicbagel/saas-kit/primitives/person-avatar";
import { Stack } from "@epicbagel/saas-kit/primitives/stack";
import { Text } from "@epicbagel/saas-kit/primitives/text";
import { CandidateFilterChips } from "@recruiteros/recruit-ui/recruit/candidate-filter-chips";
import { CandidateReviewCard } from "@recruiteros/recruit-ui/recruit/candidate-review-card";

const shares = [
  { name: "Riley Okafor", photo: "/people/riley-okafor.jpg", role: "GTM Engineer · Example Labs", viewed: true, feedback: "Can we meet Riley on Thursday?", note: "Built a seed-stage outbound system from scratch." },
  { name: "Sam Lindqvist", photo: "/people/sam-lindqvist.jpg", role: "RevOps Lead · Sample Analytics", viewed: false, feedback: "", note: "Runs campaigns and owns the tooling behind them." },
];
const filters = [{ value: "feedback", label: "Client replied" }, { value: "awaiting", label: "Awaiting feedback" }, { value: "paused", label: "Paused" }];

export function PresentListBlock() {
  const [filter, setFilter] = useState<string | null>(null);
  const [paused, setPaused] = useState<Record<string, boolean>>({});
  const visible = shares.filter(share => {
    const status = paused[share.name] ? "paused" : share.feedback ? "feedback" : "awaiting";
    return !filter || status === filter;
  });
  return (
    <Stack gap="md">
      <Text weight="semibold">Founding GTM Engineer · Presented to client</Text>
      <CandidateFilterChips value={filter} onChange={setFilter} allLabel="All shares" options={filters} />
      {visible.map(share => (
        <CandidateReviewCard key={share.name} name={share.name} headline={share.role} coverSize="compact"
          avatar={<PersonAvatar name={share.name} photoUrl={share.photo} size={40} decorative />}
          facts={[
            { label: "Share", value: paused[share.name] ? "Paused" : "Active" },
            { label: "Client opened", value: share.viewed ? "Yes" : "No" },
            { label: "Client feedback", value: share.feedback || "Awaiting feedback" },
          ]}
          insight={{ label: "Note for the client", value: share.note }}
          actions={<Button variant="outline" size="sm" onClick={() => setPaused(current => ({ ...current, [share.name]: !current[share.name] }))}>
            {paused[share.name] ? "Resume share" : "Pause share"}
          </Button>}
        />
      ))}
      {visible.length === 0 && <Text role="status">No shares in this group.</Text>}
    </Stack>
  );
}
```
</Tab>

<Tab value="API">
After the call, record who you showed with `recordPresentation`. Pass Riley’s candidate ID, the job ID and the hiring contact’s person ID, which is `ClientContact.person`. Send it once: a repeated call records a second presentation.

```graphql
mutation ShowRiley($candidateId: ID!, $jobId: ID!, $contactPersonId: ID!) {
  recordPresentation(input: {
    candidateId: $candidateId
    jobId: $jobId
    shownToPersonId: $contactPersonId
    note: "Built the outbound stack alone at seed stage."
  }) {
    presentation { id shownAt note response candidate { name } shownTo { name } }
  }
}
```
</Tab>
</Tabs>

When the client answers, save it with [`recordPresentationResponse`](/api/reference/mutations/record-presentation-response): `WANTS_INTRO`, `LATER` or `PASS`.

## 4. Give your builder the brief [#4-give-your-builder-the-brief]

Change the role, the evidence and the sharing rules below to match a search your team knows.

```text title="Copy the brief"
Build our pre-call shortlist review for one role.
Start with the fictional Founding GTM Engineer shortlist in this guide.
Let me open each person, see their evidence and read the next question.
Let me record Yes or No and a reason for this person on this role.
Keep the stage separate. Show how many people I have reviewed.
When I return to a person, show my decision and reason.
Keep reasons and open questions private. Only share a name and evidence
I explicitly select for the client. Start with sample data.
```

Start with the [review card](/ui/candidate-review-card) for the evidence, the [decision control](/ui/candidate-client-decision) for the answer and reason, and [filter chips](/ui/candidate-filter-chips) for who is left. Read one [job](/api/reference/queries/job) and its [list of candidates](/api/reference/objects/job#candidates). Each [candidate’s record on that job](/api/reference/objects/job-candidate) holds their stage, decision and reason.

## 5. Connect it to real records [#5-connect-it-to-real-records]

Once the sample review works, a workspace member can create an API key in [Kith ATS Settings](https://www.authin.ai/settings). Keep it in a server-side environment variable. If you need a workspace, [sign up for Kith ATS](https://www.authin.ai/sign-up). Give the builder the variable name and the [authentication instructions](/api#authentication). Keep the key itself out of prompts, browser code and version control.