Skip to main content
GET
Get contact by ID
GET /candidates/{id} is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.
Retrieves a single contact by ID, with their details, status and job associations.

Overview

This endpoint returns everything held about one contact: their name, how to reach them, their status, the jobs they are associated with, and your own metadata. Use it before starting a conversation, or before an update.

Use Cases

  • Display a profile: show everything you hold about someone in your own UI
  • Pre-flight check: confirm the contact exists and is reachable by your key before creating a conversation
  • Status checking: read where they have got to in your process
  • Reconciliation: confirm the record matches your other systems

Response Data

The response includes:
  • Name, email and phone number
  • Job associations (jobId and jobIds)
  • Current status
  • Gender, if set — used for gender-aware addressing on the call
  • Metadata (anything of your own: resume URL, LinkedIn, an external id)
  • fields — the contact’s catalogued field values, keyed by field key
  • Timestamps (created, updated)

fields vs metadata

Stored separately on the same contact, and only one of them reaches an agent. A field with no value is absent from fields rather than null, and {} means none are set. A value whose definition has since been deleted is omitted too — the data survives the delete and reappears if you define the key again. The catalog itself is GET /contact-fields.
Three fields are declared on the contact schema but not currently returned by any endpoint: analysisCount, interviewCount and links. Nothing populates them, so treat them as absent rather than as zero — and count conversations with List Conversations instead. interviewCount also keeps its original name; it was never given a neutral alias.

Company Isolation

You can only read contacts belonging to your API key’s company. Anything else returns 403.

Error Scenarios

  • 404 Not Found: the contact does not exist, or has been deleted
  • 403 Forbidden: the contact belongs to a different company

Contacts Resource Guide

Learn the contact structure and its status workflow

Update Contact

Change a contact’s details

List Contacts

Browse your contacts

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

id
string<uuid>
required

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
id
string
required

Contact ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

firstName
string
required

The contact's first name

Example:

"John"

lastName
string
required

The contact's last name

Example:

"Doe"

status
enum<string>
required

Contact status

Available options:
UNDEFINED,
APPLIED,
IN_PROCESS,
REJECTED,
ACCEPTED
Example:

"APPLIED"

fields
object
required

The contact's catalogued field values, keyed by field key — the counterpart of metadata, and the only half an agent can speak. Each key is defined in the company catalog (GET /contact-fields) and addressable in a flow as {{contact.<key>}}. Written through fields on POST /contacts and PATCH /contacts/{id}, never through metadata. A field with no value is absent rather than null; {} means none are set.

Example:
createdAt
string<date-time>
required

Created timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

updatedAt
string<date-time>
required

Updated timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

jobId
string
deprecated

[Deprecated] Single job ID; use jobIds instead.

Example:

"987e6543-e21b-12d3-a456-426614174000"

jobIds
string<uuid>[]

Jobs the contact is assigned to.

Maximum array length: 50
email
string

The contact's email address

Example:

"john.doe@example.com"

phoneNumber
string

The contact's phone number

Example:

"+421915123456"

gdprExpiryDate
string<date>

GDPR expiry date. Currently returned as a date (no time). NOTE: We plan to migrate to a timestamp with timezone (timestamptz) for global correctness.

Example:

"2026-11-16"

overallRating
number

Overall rating/match score (0-100)

Required range: 0 <= x <= 100
Example:

85

metadata
object

Your own scratch space on the contact: free-form, unvalidated, and never read by an agent. Replaced wholesale on update. Not the place for values you want an agent to say — those are fields.

Example:
analysisCount
number

Number of analyses for this contact. Not currently populated by any endpoint — treat as absent.

Example:

2

interviewCount
number

Number of conversations for this contact. Keeps its original field name, and is not currently populated by any endpoint — treat as absent.

Example:

3

Convenience links to related collections. Endpoints may be added incrementally.

Example:
gender
enum<string> | null

The contact's gender. Used for gender-aware addressing on the call. Null if not explicitly set (auto-detected from the name).

Available options:
male,
female
Example:

"female"

anonymizedCvText
string

The contact's anonymized CV in plain text.

Example:

"[NAME]\nSoftware Engineer\nExperience: ..."

workHistory
object[]

Work history items for the contact.

Maximum array length: 20