Candidate updates and status changes

We read before we write: to check whether a CV is already attached, to confirm a candidate still exists before posting a note, and to see the current stage and tags.

Return 404 for a candidate that has been deleted or merged away. We handle that explicitly, including the case where a create succeeded but the record was later removed as a duplicate. If you merge duplicate candidates, ideally point at the surviving record.

The response is a single candidate:

{ "candidate": {} }

These are the properties we read from it:

{
  "candidate": {
    "id": "cand_8871",
    "job_id": "job_9f3a",
    "full_name": "Jo Bloggs",
    "email": "jo.bloggs@example.com",
    "stage": { "id": "stage_2", "name": "Screening" },
    "status": "active",
    "cv": { "url": "https://ats.example.com/files/…" },
    "tags": ["first_shortlisted"],
    "created_at": "2026-08-04T09:31:22Z",
    "updated_at": "2026-08-04T10:02:11Z"
  }
}

Send only what changed. Anything we leave out must stay as it is on your record, including fields a recruiter has edited themselves.

The body is the same application object as the create payload. We send id and url every time so you can confirm which application this is; everything else arrives only when it changes. assessment is the one addition.

{
  "application": {
    "assessment": {
      "score_percentage": 0.82,
      "criteria": [
        { "name": "3+ years Go", "outcome": "met" },
        { "name": "Right to work in the UK", "outcome": "met" }
      ]
    }
  }
}

This is how your recruiters see First's work without leaving your ATS: assessment summaries, question answers, stage changes, and a link back into First.

These are the properties we send:

{
  "author_id": "user_44",
  "body": "Candidate submitted their application for Senior Backend Engineer on First.\n\n**Right to work:** Yes\n**Notice period:** 1 month\n\n[View in First](https://admin.example.com/share-application/org_1/app_88)"
}

Called when a candidate is shortlisted, stalls, or moves pipeline stage in First, so your pipeline mirrors ours.

These are the properties we send:

Behaviour we depend on:

• Return 422 rather than 500 when the move is legitimately refused (candidate already disqualified, stage not on this job's pipeline, backwards move not permitted). We log those and move on rather than retrying.
• Moving a candidate to the stage they are already in should be a no-op, not an error.
• Tell us whether a move triggers automation on your side, such as emails to candidates or scorecard requests. Customers must know before they turn stage sync on.

{ "target_stage": "stage_3", "author_id": "user_44" }

Called when a candidate is rejected in First, withdraws, or goes unresponsive.

These are the properties we send:

First distinguishes four cases, and you map each onto one of your reasons:

Same 422 rule as stage moves: business-rule refusals must not look like server errors. Disqualifying an already-disqualified candidate should be a no-op. If you have a way to undo a disqualification, tell us. We do not call one today, but we would like to know it exists.

{
  "reason_id": "reason_1",
  "author_id": "user_44",
  "note": "Did not meet must-have criteria: 3+ years Go"
}

Only build this if fetching a URL is awkward for you. Part one puts a signed cv.url on the create payload for you to fetch, which is less work on both sides. This endpoint is the alternative: we send you the bytes.

When we call it: once the application exists and the candidate has uploaded a CV.

The body is multipart/form-data with a single part:

Accept PDF and DOCX at minimum. We send the file unconverted, so it can also arrive as RTF, TXT, Markdown or HTML. Tell us if any of those would be rejected, and whether a second upload replaces the first or adds another.

POST /applications/app_88/cv
Content-Type: multipart/form-data; boundary=----first

------first
Content-Disposition: form-data; name="file"; filename="Jo_Bloggs_CV.pdf"
Content-Type: application/pdf

<binary>
------first--