# Run a job from intake to placement (/workflows/headless-ats)

Alex Marchetti at Example Studio calls you about an engineering director role. You think Sam Lindqvist might be a good fit. Here’s how you’d work that job in Kith ATS.

If this is your first time using the API, [make your first request in a test workspace](/api#making-a-request).

## 1. Open the job for Alex [#read-the-graphql]

Create Example Studio with `addCompany`, using `CLIENT` as the relationship. Use the company ID to add Alex as the hiring contact with `addClientContact`. Pass the same ID as `$clientId` when you open the job. Keep the job ID for when you put Sam forward.

<Tabs items={["API","UI"]}>
<Tab value="API">
```graphql
mutation OpenRole($clientId: ID!) {
  createJob(input: { companyId: $clientId, title: "Engineering Director" }) {
    job { id title status client { id name } }
  }
}
```
</Tab>

<Tab value="UI">
The [job status block](/blocks/job-status) shows Alex beside the opening, so you can see who to call about the role.

<UiPreview slug="job-status" title="Example Studio’s open role" minHeight={180} />

```tsx
"use client";

import { useState } from "react";
import { JobStatusBlock } from "@recruiteros/recruit-ui/blocks";

export function JobStatusExample() {
  const [status, setStatus] = useState<"OPEN" | "CLOSED">("OPEN");
  return <JobStatusBlock
    title="Engineering Director"
    client="Example Studio"
    contact="Alex Marchetti"
    contactPhotoUrl="/people/alex-marchetti.jpg"
    statusLabel={status === "OPEN" ? "Open" : "Closed"}
    onClose={status === "OPEN" ? () => setStatus("CLOSED") : undefined}
  />;
}
```
</Tab>
</Tabs>

Alex asks who’ll be on the interview panel. Give a teammate the task “Confirm the interview panel” and close it when they have the names. [Work through a team task](/workflows/team-tasks) · [Download the task calls](/examples/recruiting-tasks.graphql)

## 2. Put Sam forward and record the screen [#2-put-sam-forward-and-record-the-screen]

After a call with Sam, you agree the role is worth pursuing. Use `addCandidates` to get Sam’s candidate ID, then pass it and the job ID to `addCandidatesToJob`. That gives you an application ID and a version. Use those to record the screen on this job.

<Tabs items={["API","UI"]}>
<Tab value="API">
```graphql
mutation RecordScreen($applicationId: ID!, $version: String!) {
  moveJobCandidate(input: {
    jobCandidateId: $applicationId
    expectedVersion: $version
    stage: SCREENED
  }) {
    jobCandidate { id stage version candidate { name photoUrl bannerUrl } }
  }
}
```
</Tab>

<Tab value="UI">
Try moving Sam to **Screened** in the [application pipeline](/blocks/application-pipeline). In your app, show the stage returned by `moveJobCandidate`.

<UiPreview slug="application-pipeline" title="Sam’s stage on this job" minHeight={240} />

```tsx
"use client";

import { useState } from "react";
import { ApplicationPipelineBlock } from "@recruiteros/recruit-ui/blocks";

const options = [
  { value: "SOURCED", label: "Sourced" },
  { value: "SCREENED", label: "Screened" },
];

export function ApplicationPipelineExample() {
  const [stage, setStage] = useState("SOURCED");
  return <ApplicationPipelineBlock
    profile={{ name: "Sam Lindqvist", photoUrl: "/people/sam-lindqvist.jpg" }}
    title="Applications"
    rows={[{
      id: "sam-engineering-director",
      title: "Engineering Director",
      subtitle: "Example Studio",
      stage: { value: stage, options, onChange: setStage },
    }]}
  />;
}
```
</Tab>
</Tabs>

When Sam is ready to meet the client, [save the CV and introduce Sam to Alex](/workflows/introduce-a-candidate).

## 3. Book the interview and save Alex’s feedback [#3-book-the-interview-and-save-alexs-feedback]

Alex and Sam settle on Tuesday at 2 pm UTC. Send the invitation through your calendar and record the appointment on Sam’s application.

<Tabs items={["API","UI"]}>
<Tab value="API">
```graphql
mutation BookInterview($applicationId: ID!) {
  scheduleInterview(input: {
    jobCandidateId: $applicationId
    label: "Technical interview"
    scheduledAt: "2027-01-12T14:00:00Z"
    interviewer: "Alex Marchetti"
  }) {
    interview { id label interviewer scheduledAt status version }
  }
}
```
</Tab>

<Tab value="UI">
Try the [interview scheduler](/blocks/interview-scheduler). Book Tuesday’s appointment, change the date, then record Alex’s feedback. This example saves your edits in the preview.

<UiPreview slug="interview-scheduler" title="Sam’s interview with Alex" minHeight={160} />

```tsx
"use client";

import { useState } from "react";
import { InterviewScheduler, type ScheduledInterview } from "@recruiteros/recruit-ui/blocks";

export function InterviewSchedulerExample() {
  const [appointment, setAppointment] = useState<ScheduledInterview | null>(null);

  return <InterviewScheduler
    candidate="Sam Lindqvist"
    candidateMedia={{ photoUrl: "/people/sam-lindqvist.jpg" }}
    role="Engineering Director"
    appointment={appointment}
    defaults={{
      label: "Technical interview",
      scheduledAt: "2027-01-12T14:00:00Z",
      interviewer: "Alex Marchetti",
    }}
    timeZone="America/New_York"
    timeZoneLabel="Sam in New York"
    onSchedule={details => setAppointment({
      ...details, id: "17", version: "1", status: "SCHEDULED",
    })}
    onUpdate={(original, edit) => setAppointment({
      ...original, ...edit, version: String(Number(original.version) + 1),
    })}
  />;
}
```
</Tab>
</Tabs>

Move Sam to `INTERVIEWING` with `moveJobCandidate`. When Alex asks to move the meeting to Wednesday, pass the interview ID, its version and the new time to `updateInterview`. After the meeting, use the version from that last edit to save Alex’s feedback and mark the appointment `COMPLETED`.

If Alex later asks when the meeting moved, use the interview ID to read `Interview.changes`. The newest entry comes first. You can see the original and revised times, who made the edit, and whether feedback changed. The interview itself holds Alex’s current feedback. [Read an interview’s history](/api/reference/objects/interview#changes)

If Sam confirms by email, you can keep the original message and reply together on their record. [Work through an email exchange](/workflows/message-threads)

Alex wants a day to talk with the team. On Sam’s application, save “Call Alex for a decision” and a Friday due time with [`updateJobCandidateFollowUp`](/api/reference/mutations/update-job-candidate-follow-up). Use the application’s latest `version`. When you’ve spoken to Alex, clear `nextAction` and `nextActionDueAt` together and keep the returned version for the offer.

## 4. Record the offer and Sam’s acceptance [#4-record-the-offer-and-sams-acceptance]

Alex offers Sam £85,000. Your agency’s fee is £17,000. Move Sam to `OFFERED` and ask for `placementVersion` in the response. That’s the version you need to save the terms.

<Tabs items={["API","UI"]}>
<Tab value="API">
```graphql
mutation RecordOffer($applicationId: ID!, $placementVersion: String!) {
  updatePlacement(input: {
    jobCandidateId: $applicationId
    expectedVersion: $placementVersion
    offerSalary: "85000.00"
    currency: "GBP"
    placementFee: "17000.00"
  }) {
    jobCandidate { stage offerSalary placementFee currency version }
  }
}
```
</Tab>

<Tab value="UI">
Show Sam’s salary and the agency fee together in the [placement terms block](/blocks/placement-terms).

<UiPreview slug="placement-terms" title="Sam’s offer and the agency fee" minHeight={180} />

```tsx
import { PlacementTermsBlock } from "@recruiteros/recruit-ui/blocks";

const money = new Intl.NumberFormat("en-GB", {
  style: "currency", currency: "GBP", maximumFractionDigits: 0,
});

export function PlacementTermsExample() {
  return <PlacementTermsBlock
    candidate="Sam Lindqvist"
    candidateMedia={{ photoUrl: "/people/sam-lindqvist.jpg" }}
    role="Engineering Director"
    salary={money.format(85000)}
    fee={money.format(17000)}
  />;
}
```
</Tab>
</Tabs>

Sam accepts on 20 January and agrees to start on 1 February. Use the application `version` from the saved offer to move Sam to `HIRED`. Use the `placementVersion` from that move to save `offerAcceptedAt` and `startDate` with `updatePlacement`.

## 5. Close the job [#5-close-the-job]

Alex confirms Sam was the only hire. You can now close the opening.

<Tabs items={["API","UI"]}>
<Tab value="API">
```graphql
mutation CloseRole($jobId: ID!) {
  setJobStatus(input: { jobId: $jobId, status: CLOSED }) {
    job { id title status }
  }
}
```
</Tab>

<Tab value="UI">
Select **Close job** in the [job status block](/blocks/job-status). In your app, show Closed when `setJobStatus` returns the updated role.

<UiPreview slug="job-status" title="Closing the engineering director role" minHeight={220} />

```tsx
"use client";

import { useState } from "react";
import { JobStatusBlock } from "@recruiteros/recruit-ui/blocks";

export function JobStatusExample() {
  const [status, setStatus] = useState<"OPEN" | "CLOSED">("OPEN");
  return <JobStatusBlock
    title="Engineering Director"
    client="Example Studio"
    contact="Alex Marchetti"
    contactPhotoUrl="/people/alex-marchetti.jpg"
    statusLabel={status === "OPEN" ? "Open" : "Closed"}
    onClose={status === "OPEN" ? () => setStatus("CLOSED") : undefined}
  />;
}
```
</Tab>
</Tabs>

When Alex calls back to check the start date, read Sam’s application with `jobCandidate`. The agreed terms and interview feedback are still there. If you need the dates Sam moved through the process, read the job’s `auditTrail` filtered by Sam’s candidate ID. The `actor` on a move tells you who made it. If a Recruit agent moved Sam, `actor.kind` is `AGENT` and `actor.label` gives its name. Older moves can have an unknown actor. [Read the audit actor](/api/reference/objects/audit-actor)

You can run the whole example in [Python](/examples/placement.py) or [Node.js](/examples/placement.mjs), or download the [GraphQL operations](/examples/ats-lifecycle.graphql).