Skip to main content

​
List your candidates

GET /recruiter/candidates (candidates:read) returns the candidates you own in your Paraform CRM, newest first. Hidden and archived candidates are left out.
Each candidate has furthestStatus, the furthest pipeline status any of their applications reached (for example SUBMITTED, INTERVIEWING, OFFER, or HIRED), or null if you’ve never submitted them. relationshipStatus is your working relationship with them, separate from any application.
Agency owners, and members of agencies that share candidates, see more candidates in the app than this endpoint returns. The API only returns candidates you own.
GET /recruiter/candidates/{candidateId}/recommended-roles (candidates:read and roles:read) returns the roles Paraform’s matching recommends for a specific candidate, strongest first. candidateId is the candidateId from the candidate list.
  • recommendation.band is ENDORSED (a strong match) or SUGGESTED (worth a look).
  • Each role carries the same fields as GET /recruiter/roles, including myRole and fee.
  • The list is short by design, at most about 15 roles. It already leaves out roles the candidate was submitted to and roles Paraform is still assessing.
  • An empty list means no recommendations were found for this candidate right now.
Use this endpoint whenever a particular candidate is in mind, rather than filtering GET /recruiter/roles yourself. It’s backed by Paraform’s matching model, which reads the candidate’s full profile.

​
Recommendations across your whole CRM

GET /recruiter/recommendations (candidates:read and roles:read) returns the Recommended submissions list from your Paraform home page: the roles recommended for every candidate in your CRM.
  • Returns at most 20 (candidate, role) pairs, strongest first. ENDORSED pairs come before SUGGESTED ones.
  • Candidates are ordered by their strongest pair, and each candidate’s roles strongest first.
  • Already leaves out recently hired candidates, roles a candidate was already submitted to, and roles you can’t submit to.
  • enabled tells you whether recommendations are on for your account. An empty list with enabled: true means there are no active recommendations right now.
For one named candidate, use the per-candidate endpoint above instead. Don’t loop it over your whole CRM, because this call returns the same rows in one request.