Overview
When someone applies for a role on your website, you can use the Atlas API to:
Add them to your Atlas contacts (or update them if they already exist)
Place them as a candidate in the relevant project at the correct pipeline stage
For full endpoint details, refer to the API documentation here.
How it works
Step 1 — Add the person to Atlas
Send a POST request to the People endpoint with the applicant's details. At minimum you need their name and one contact detail — email, phone, or LinkedIn URL.
Atlas will do one of two things:
If the person doesn't exist yet — a new contact record is created and their
personIdis returnedIf someone with a matching contact detail already exists — their existing record is updated and their
personIdis returned
Either way, you get back a personId which you'll need for the next step.
Key fields to include:
identities— at least one of: email, phone, or LinkedIn URL (required)firstName/lastNameaddedByEmail— the email of the Atlas user this action should be attributed toexperience,education,address— optional but recommended if available from the application form
Step 2 — Find the correct project and pipeline stage
Before placing the candidate, you need the id of the project they applied to, and optionally the stageId or statusId of where in the pipeline they should land.
To find these, call the Get Project Details endpoint for the relevant role. This returns the full pipeline with all stage and status IDs.
If you don't provide a stage or status, Atlas will automatically place the candidate at the very first status of the first stage.
Step 3 — Add them as a candidate
Send a POST request to the Create Candidate endpoint, providing:
The
project IDin the URL pathThe
personIdfrom Step 1 in the request bodyOptionally, a
statusIdorstageIdto control where they land in the pipeline
POST https://api.recruitwithatlas.com/api/v1/projects/{id}/candidates
Atlas will return the newly created candidate record, including the candidate ID, person ID, project ID, and the pipeline status they were placed at.
Pipeline placement — how it works
What you provide | Where the candidate lands |
| Exactly at that status |
| First status within that stage |
Neither | First status of the first stage |
Note: if you provide both statusId and stageId, the statusId takes priority and stageId is ignored.
Things to keep in mind
You need a valid Atlas API key for both the People and Create Candidate endpoints
The
addedByEmailmust match an existing user in your Atlas account, otherwise the request will failIf the same person applies multiple times, Atlas will not create a duplicate — it will update their existing record and you will receive their existing
personIdIf a
personIdor projectidcannot be found, a 404 response is returned