RErecruitwithatlas
People

Create a note on a person

Changed on

Use this endpoint to add a written note to a person's record in Atlas.

Notes are a way of recording important context about a candidate or contact - for example, a summary of a phone call, a reminder about their availability, or any other information you want to log against them.

Identifying the person: Provide exactly one of:

  • email - the person's email address. Atlas finds the person by matching against their stored email identities.
  • personId - the Atlas person ID. Atlas looks the person up directly within your agency.
  • linkedinUrl - the person's LinkedIn profile URL. Atlas normalises the URL (stripping protocol, www., trailing slash, case) before matching against the person's stored LinkedIn identity. Public profile (linkedin.com/in/...), Talent/Recruiter, and Sales Navigator URLs are all supported.
  • phone - the person's phone number. Atlas matches against stored phone identities across common formatting variations. The number must map to exactly one person; if it is ambiguous (matches more than one person) the request returns 404 and you should use personId instead.

If zero or more than one identifier is supplied, the request is rejected with a 422 validation error.

Identifying the note author:

  • ownerEmail - the email address of the Atlas user the note should be attributed to.

What you also provide:

  • The text content of the note (note)
  • projectId (optional) - an Atlas project ID to scope the note to that person's candidacy on the project, the same way a note added from a project's candidate drawer is scoped inside Atlas. When set, the note shows only on that project's candidate drawer; when omitted the note is person-level and shows everywhere. A projectId that does not exist in your agency is rejected with a 404.

The note will be created as type manual and will appear on that person's timeline inside Atlas, visible to your team.

Each call adds a new note. To change a note's text later, use Update a note with the returned id; to remove it, use Delete a note.

put/api/v1/people/notes

Request

Request body

emailstring email

Person's email address. Provide exactly one of email, personId, linkedinUrl, or phone.

personIdstring uuid

Atlas person ID. Provide exactly one of email, personId, linkedinUrl, or phone.

linkedinUrlstring

Person's LinkedIn profile URL. Provide exactly one of email, personId, linkedinUrl, or phone.

phonestring

Person's phone number. Provide exactly one of email, personId, linkedinUrl, or phone.

notestring required

Note text to create

ownerEmailstring email required

Note owner's email address

projectIdstring uuid

Atlas project ID to scope the note to the person's candidacy on that project. Omit for a person-level note.

Example request

{
  "email": "person@example.com",
  "personId": "123e4567-e89b-12d3-a456-426614174000",
  "linkedinUrl": "linkedin.com/in/john-doe",
  "phone": "+14155551234",
  "note": "Called and left a voicemail.",
  "ownerEmail": "recruiter@agency.com",
  "projectId": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}

Response

Note created

status'ok' required

Changes