Skip to main content
GET
List contacts
GET /candidates is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.
Lists your contacts, with pagination and filtering.

Overview

This endpoint returns the contacts belonging to your API key’s company. You can filter by job or status, search by name or email, and page through the results — useful for finding someone before starting a conversation with them.

Use Cases

  • Browse your contacts: review everyone your company holds
  • Job-specific filtering: narrow to the contacts assigned to one job
  • Status tracking: filter by where someone has got to in your process
  • Search: locate a contact by name or email

Basic Usage

With Filters

status is one of UNDEFINED, APPLIED, IN_PROCESS, REJECTED or ACCEPTED. The names are hiring-flavoured because they predate the neutral vocabulary; they are the values the API accepts, so they are unchanged.

Company Scoping

Every contact returned belongs to your API key’s company. Contacts from other companies are filtered out.

Contacts Resource Guide

Learn about managing contacts, status workflows, and filtering

Pagination Guide

Understand pagination best practices

Get Contact

Retrieve a single contact by ID

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

page
integer
default:1

Page number (1-based)

Required range: 1 <= x <= 10000
Example:

1

limit
integer
default:20

Number of items per page

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

20

companyId
string<uuid>

Company ID (required for ATS keys, optional for regular keys)

Example:

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

jobId
string<uuid>

Filter by job ID

Example:

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

status
enum<string>

Filter by contact status

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

"APPLIED"

Search by name (first or last name)

Example:

"John"

Response

200 - application/json
data
object[]
required

Array of contacts

total
number
required

Total number of items

Example:

150

page
number
required

Current page number

Example:

1

limit
number
required

Number of items per page

Example:

20

totalPages
number
required

Total number of pages

Example:

8