Skip to main content
GET
List candidates

Authorizations

Authorization
string
header
required

An Enrik API key, sent as Authorization: Bearer <key>. A key reaches public operations only, and only those whose scopes it holds. A few parameters need a scope beyond their operation’s, which the parameter names. The scopes:

  • setup:read: Read the workspace setup and its company profile.
  • setup:run: Change the setup: confirm the company profile, authorize sponsored drafting and background company research, choose what to set up and complete setup.
  • workspace:read: Read the workspace’s own profile: its health summary and setup state.
  • crm:read: Read companies with their signals, contacts and the saved views over them.
  • crm:write: Create, update and restore companies and contacts, and create, update and delete saved views.
  • crm:delete: Delete companies and contacts.
  • twin:read: Read the Company Twin: structured company knowledge and its signals.
  • discovery:read: Read ICP profiles, ICP assessments, discovery briefs, discovery jobs, candidates and the signal library.
  • discovery:write: Create and change ICP profiles, discovery briefs and signal-definition drafts, and review discovery candidates.
  • discovery:run: Create, start and cancel discovery jobs, and edit a draft one. Uses provider budget.
  • enrichment:read: Read the enrichment configuration and its results, including a record’s enrichment, formula and custom-API cells.
  • enrichment:run: Launch and cancel enrichment. Spends enrichment credits.
  • automation:read: Read workflows and agents with their run history, including a record’s agent cells.
  • automation:run: Run existing workflows and agents.
  • exports:read: Read export jobs and the fields an export can carry.
  • exports:run: Create, preview, start, cancel and archive CSV exports of companies, contacts and candidates, and download the file. Also needs crm:read. Delivering an export to a webhook destination stays in the app.
  • integrations:read: Read connections, field mappings, CRM sync jobs and webhook destinations.
  • webhooks:read: Read webhook subscriptions, the event types they can name and their delivery log.
  • webhooks:write: Subscribe a receiver URL to webhook events; edit, test, pause, resume and archive a subscription and rotate its signing secret; redeliver an event. Only workspace owners and admins can grant it.
  • reporting:read: Read analytics and dashboards.
  • assistant:read: Read the Assistant: its threads, messages and pending approvals.
  • assistant:run: Converse with the Assistant. Uses the workspace’s AI quota.
  • assistant:write: Approve or reject the changes the Assistant proposes.

Headers

If-None-Match
string

The ETag of an answer you kept. While the answer is still the same, the API answers 304 Not Modified with no body. Several tags, separated by commas, a weak tag (W/"…") and * are accepted.

Query Parameters

rankingMode
enum<string>

Rank the candidates: icp_only against the ICP profile, contextual against a brief.

Available options:
icp_only,
contextual
sort
enum<string>

Sort by one score, highest first, or by createdAt, newest first. A ranked list sorts by contextual_priority, and only by it. Without it, candidates come by review priority.

Available options:
reviewPriorityScore,
candidateIcpFitScore,
candidateQualityScore,
candidateEvidenceScore,
createdAt,
contextual_priority
briefId
string<uuid>

A contextual ranked list: the brief to rank against.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
briefVersionId
string<uuid>

A contextual ranked list: the exact brief version to rank against.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
snoozed
enum<string>

A ranked list: leave snoozed candidates out (exclude, the default), in, or only.

Available options:
exclude,
include,
only
customerStatus
enum<string>

A ranked list: only candidates with this customer status.

Available options:
customer,
not_customer,
unavailable
salesWorkState
enum<string>

A ranked list: only candidates in this state of sales work.

Available options:
in_sales_work,
not_in_sales_work,
unavailable
cursor
string

Where to resume a list: the previous page’s pageInfo.endCursor. Opaque.

Minimum string length: 1
discoveryJobId
string<uuid>

Only the candidates of this discovery job.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
status
enum<string>

Only candidates in this status.

Available options:
new,
needs_review,
accepted,
rejected,
archived,
promoted,
linked_existing,
failed
dedupeStatus
enum<string>

Only candidates with this duplicate status.

Available options:
unchecked,
no_match,
possible_duplicate,
existing_company_match,
duplicate_candidate
scoringStatus
enum<string>

Only candidates with this scoring status.

Available options:
unscored,
scored,
failed,
stale
reviewPriorityTier
enum<string>

Only candidates in this review-priority band.

Available options:
high_priority,
medium_priority,
low_priority,
reject_likely,
insufficient_data

Only candidates with this recommended next action.

Available options:
promote_candidate,
review_manually,
verify_domain,
possible_duplicate_review,
reject_candidate,
insufficient_data
sourceType
enum<string>

Only candidates from this kind of source.

Available options:
pasted_list,
manual_candidate,
user_provided_source_page,
controlled_source,
csv_upload,
enrik_data,
infobel_firmographics
sourceCategory
enum<string>

Only candidates from this category of controlled source.

Available options:
trade_fair_exhibitor,
event_sponsor,
industry_directory,
association_member_list,
conference_partner,
other_structured_b2b_list
minReviewPriorityScore
string

Only candidates with at least this review priority, 0 to 100. Empty means no minimum.

minIcpFitScore
string

Only candidates with at least this ICP fit, 0 to 100. Empty means no minimum.

limit
integer
default:50

How many items to return: 1 to 200, 50 when absent.

Required range: 1 <= x <= 200

Response

A page of candidates: by review priority, by the sort asked for, or ranked (rankingMode).

A page of candidates: by review priority, by the sort asked for, or ranked (rankingMode).

data
object[]
required

The items on this page, in order.

pageInfo
object
required

Where this page ends, and whether another follows.

contextualRanking
object
required

Whether a ranked list can be asked for.