Create a candidate

Use this endpoint to add a person from your Atlas contacts into a specific project as a candidate - moving them into the recruitment pipeline for that role.

For example, if you receive a job application through your website and have already added the person to Atlas (using the People endpoints), you can use this endpoint to automatically add them as a candidate to the relevant project, at the right stage of the pipeline.

What you need to provide:

• The project ID in the URL path - the project you want to add them to
• The person ID in the request body - the Atlas ID of the person you are adding as a candidate
• Optionally, a statusId or stageId to control where in the pipeline they are placed (see below)

How pipeline placement works:

Every project in Atlas has a pipeline made up of stages (e.g. Sourcing, Longlist, Shortlist) and within each stage there are statuses (e.g. Added, Reviewed, Approved). When you add a candidate, you can control exactly where they land:

• If you provide a statusId - the candidate is placed at that exact status. The stageId is ignored if both are provided.
• If you provide only a stageId - the candidate is placed at the first status within that stage.
• If you provide neither - the candidate is placed at the very first status of the very first stage (the default starting point).

To find the correct statusId or stageId for a project, first 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.

What you get back: The newly created candidate record, including the candidate ID, person ID, project ID, and the status they were placed at.