New: Kith open-sources its ATS.Read why
Skip to Content

Run a job from intake to placement

Work through an agency placement, from opening the job to recording the hire and closing the role.

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.

1. Open the job for Alex

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.

mutation OpenRole($clientId: ID!) {
  createJob(input: { companyId: $clientId, title: "Engineering Director" }) {
    job { id title status client { id name } }
  }
}

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 · Download the task calls

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.

mutation RecordScreen($applicationId: ID!, $version: String!) {
  moveJobCandidate(input: {
    jobCandidateId: $applicationId
    expectedVersion: $version
    stage: SCREENED
  }) {
    jobCandidate { id stage version candidate { name photoUrl bannerUrl } }
  }
}

When Sam is ready to meet the client, save the CV and introduce Sam to Alex.

3. Book the interview and save Alex’s 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.

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 }
  }
}

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

If Sam confirms by email, you can keep the original message and reply together on their record. Work through an email exchange

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. 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

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.

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 }
  }
}

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

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

mutation CloseRole($jobId: ID!) {
  setJobStatus(input: { jobId: $jobId, status: CLOSED }) {
    job { id title status }
  }
}

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

You can run the whole example in Python or Node.js, or download the GraphQL operations.