Read candidates, notes and scorecards

Use the candidate ID from a candidate record or an application’s candidate.id. A candidate can have applications on several jobs. All example IDs are fictional.

1. Find and read the candidate

curl --fail-with-body "https://api.join.com/v3/candidates?q=ada&limit=10" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-01"

Search results use relevance order. Do not send sort with q. To browse by creation date instead, omit q and use the supported sort parameter. See List candidates and Pagination, filtering and sorting.

Read Get a candidate for the profile, consent status and application summaries. To read a full application, pass its application ID to Get an application.

2. Work with notes under Candidates

curl --fail-with-body "https://api.join.com/v3/candidates/7788/notes?limit=10" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-01"

Company tokens can read private notes as well as shared notes; isPrivate controls recruiter visibility in JOIN. Each note includes its replies.

To add a shared note:

curl --fail-with-body "https://api.join.com/v3/candidates/7788/notes" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-01" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
  "content": "Available for an interview next week."
}'

Notes keep the content supplied at creation. Review the text before submitting; it cannot be edited later. See Create a candidate note for content and per-candidate limits. Deleting a note also deletes its replies and reactions.

3. Read scorecards

curl --fail-with-body "https://api.join.com/v3/scorecards?candidateId=7788" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-01"

Use candidateId to retrieve published interview feedback across a candidate’s applications, including earlier or withdrawn applications. Results are ordered by creation date, oldest first, and returned together in a single response. See List candidate scorecards.

Candidate deletion

Delete a candidate permanently removes the candidate and their applications, notes and attachments. It is not a way to remove just one application from a job. Review the scope before using it for an erasure request; the operation cannot be undone.