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.
PARAMS
| key | {{api_key}} required |
| scope | candidate required |
| fields | departmentIds, firstName, lastName, education, mobilePhone, email required |
| page | 1 required |
| updated | 2017-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 | 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 operation: 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 integer | Department IDs to connect the candidate to |
| userIds array of integer | User IDs to connect the candidate to |
| companyIds / companyContactIds array of integer | Company / company contact IDs to connect the candidate to |
| blockCompanyIds array of integer | 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 integer | 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.