RErecruitwithatlas
Projects

Move a candidate to a different stage or status

Changed on

Move an existing candidate to a different stage or status within the same project pipeline.

How pipeline placement works:

  • If you provide a statusId - the candidate is moved to that exact status. stageId is ignored if both are provided.
  • If you provide only a stageId - the candidate is moved to the first status within that stage.

To find the correct statusId or stageId for a project, call the Get project details endpoint - it returns the full pipeline with all stage and status IDs.

Hiring: when the target status is in the Hired stage, Atlas creates a placement for the candidate. If your agency has Contracts enabled you must say which kind with placementType (permanent or contract). There is no default - a hired target without placementType is rejected with 400. If Contracts is off, every hire is permanent: placementType can be omitted, and contract is rejected with 400.

Contract hires: with placementType: "contract" you must also send contract - the contract startDate and base rate (unit, chargeRate, payRate, currency), plus optional endDate, daysPerWeek and hoursPerDay. Atlas records them as a draft contract linked to the placement, on the default payment terms of the agency, for the recruiter to review and activate in Atlas. A contract hire without contract is rejected with 400. contract is rejected with 422 when placementType is not contract, and with 400 when the target status is not in the Hired stage. This covers re-hiring someone whose earlier contract ended. contract is ignored only when the candidate is already in the Hired stage with a placement, since that move hires nobody. A candidate in Hired without a placement is hired by the move, so contract is required.

Returns 422 when:

  • The project is closed
  • The candidate has been rejected (the rejection must be rolled back first)
patch/api/v1/projects/{projectId}/candidates/{candidateId}/move

Request

Path parameters

projectIdstring uuid required

Project ID

Example:550e8400-e29b-41d4-a716-446655440000
candidateIdstring uuid required

Candidate ID

Example:550e8400-e29b-41d4-a716-446655440004

Request body

statusIdstring uuid

Target status ID. When provided, stageId is ignored

stageIdstring uuid

Target stage ID — candidate is moved to the first status of this stage. Ignored when statusId is provided

placementType'permanent' | 'contract'

Type of placement to create when the target status is in the Hired stage. Required for hired targets when the agency has Contracts enabled — the request fails with 400 without it. With Contracts off every hire is permanent: omit it or send permanent; contract fails with 400. Ignored for any other stage.

Example request

{
  "statusId": "550e8400-e29b-41d4-a716-446655440002",
  "stageId": "550e8400-e29b-41d4-a716-446655440003",
  "placementType": "permanent",
  "contract": {
    "startDate": "2026-10-01",
    "endDate": "2027-03-31",
    "daysPerWeek": 5,
    "hoursPerDay": 8,
    "rate": {
      "unit": "daily",
      "chargeRate": "650.00",
      "payRate": "500.00",
      "currency": "GBP"
    }
  }
}

Response

Candidate moved

status'ok' required

Changes

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status

  • bfc1118eeb5dRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the non-success response with the status