In this article, you can read about how to retrieve candidate data via the API – listing candidates, searching, filtering by candidate ID range, and viewing the full candidate field reference.
List Candidates
Retrieving data about candidates is done through the GET method. You can either list candidates or search for specific ones. Each request must define a page number; up to 100 candidates are returned per page.
https://api.recman.io/v2/get/?key={{api_key}}
&scope=candidate&fields=departmentIds,firstName,
lastName,education,mobilePhone,email&page=1If you want to fetch 200 candidates, you will need two separate requests: &page=1 for candidates 1–100, and &page=2 for candidates 101–200.
Each response includes a numRows value showing how many candidates were returned. Requesting a page beyond your available candidates returns numRows: 0. For instance, if you request page 3, but only have 180 candidates in your database.
Show candidates that have been updated after a specific date & time
Retrieve a list of all candidates updated after a given date and time. Dateformat is Y-m-d%Hi:s:u
...&scope=candidate&fields=firstName&page=1&updated=2017-12-10 00:00:00
Retrieve only candidates connected to a specific department
To view all candidates connected to a specific department, add the parameter departmentId and the ID of the department.
...&scope=candidate&fields=firstName&departmentId=1193
Request only employees
You can choose to only get candidates who have the status “employee” from the system. To accomplish this, simply add &isEmployee=1. You can also add a 0, which returns candidates who are NOT employees.
...&scope=candidate&candidateId=298128&isEmployee=1
PARAMS
| key | {{api_key}} required |
| scope | candidate required |
| fields | departmentIds, firstName, lastName, education, mobilePhone, email required |
| page | 1 required |
| updated | 2025-12-10 00:00:00 optional – returns candidates updated after this date/time. Format: Y-m-d H:i:s |
| departmentId | 1193 optional – returns only candidates connected to this department |
| isEmployee | 1 optional – 1 returns only employees, 0 returns only non-employees |
Get Specific Candidate / Search Candidates
You can look up a single candidate by adding the candidateId parameter (limited to one lookup), or search by email, mobilePhone, firstName, and/or lastName – these can be combined in a single request.
GET
https://api.recman.io/v2/get/?key={{api_key}}
&scope=candidate&fields=firstName,lastName,education,
mobilePhone,email&page=1&candidateId=982575PARAMS
| key | {{api_key}} required |
| scope | candidate required |
| fields | departmentIds, firstName, lastName, education, mobilePhone, email required |
| page | 1 required |
| candidateId | 982575 optional – limits results to one specific candidate |
| johnny@recman.no optional |
|
| mobilePhone | 92808102 optional |
| firstName | johnny optional |
| lastName | appleseed optional |
| corporationId | 2 optional |
Get Candidates Limiting by Candidate ID
You can list all candidates from a certain ID onwards – useful for limiting your request to candidates created after a certain point.
GET
https://api.recman.io/v2/get/?key={{api_key}}
&scope=candidate&fields=firstName,lastName,education,
mobilePhone,email&page=1&minCandidateId=3772436PARAMS
| key | {{api_key}} required |
| scope | candidate required |
| fields | firstName, lastName, education, mobilePhone, email required |
| page | 1 required |
| minCandidateId | 3772436 optional |
Get Candidate's Fields
This is the full reference of fields available on the candidate scope, including all nested objects. Use it to decide which fields to pass in the fields parameter of a GET request, or as a reference when inserting/updating.
Note
mobilePhone, homePhone, and officePhone are deprecated. They are still supported, but it's recommended to use phoneList instead.
Candidate Fields
| Fields | Description |
|---|---|
| candidateId integer |
Candidate ID. Required on operations: update, delete |
| corporationId integer |
Required on operation: insert |
| firstName string |
First name of candidate |
| lastName string |
Last name of candidate |
| title string |
Title |
| email / officeEmail string |
Email addresses |
| phoneList object |
Phone list. Preferred over deprecated mobilePhone / homePhone / officePhone |
| gender string |
Valid values: male, female |
| maritalStatus string |
Marital status |
| dob date |
Date of birth. Format: Y-m-d |
| workStatus string |
Work status |
| description / notes string |
Free-text description / notes |
| departmentIds array of integers |
Department IDs to connect the candidate to |
| userIds array of integers |
User IDs to connect the candidate to |
| companyIds / companyContactIds array of integers |
Company / company contact IDs to connect the candidate to |
| blockCompanyIds array of integers |
Company IDs to block. POST only |
| blockedCompanies integer |
List of blocked company IDs. GET only |
| banned boolean |
If candidate is banned. POST only. Valid values: 0, 1 |
| children array of integers |
Birth year per child. Valid values: 4-digit year |
| rating string |
Rating 0–5. Valid values: 1, 2, 3, 4, 5 |
| facebook / linkedin / twitter / web string |
Social/web URLs |
| created / updated string |
When the candidate profile was created / last changed |
| nationality string |
Valid values: ISO_3166-1 standard – Alpha-code 2 |
| languageId integer |
Language ID |
| address1 / address2 / postalCode / city / country string |
Address fields |
| driversLicense array of strings |
Valid values: A, A1, B, BE, D, D1, D1E, DE, C, C1, C1E, CE, M, T, TRUCK |
| profilePicture string |
GET only, returns URL to image |
| password string |
Password. POST only |
| experience, education, certification, language, dependents, employee, employment, skills, reference, file, profilePictures, pipeline, attributes, interview, hpr, jobApplication, referenceCheck, workLocation, salaryMatrixCategory, termsAccepted, dialogue, projectExperience object |
Nested objects – see Candidates: Creating Candidates and Nested Data via the API for how to insert each one. |
What's next
Continue with Candidates: Creating Candidates and Nested Data via the API to insert a candidate and attach nested data, or Candidates: Updating, Deleting, and Managing Files via the API to modify or remove existing data.