Get Candidates
Retrieving data about candidates are done through the GET method.
You can either do a request to list candidates or to search for candidates.
Details about how to do a GET request to retrieve candidates will be described on this page. A list of available fields for this request can be found on the candidate reference page.
| URL | https://api.recman.no/v2/get/ |
| Scope | candidate |
| Fields | Fields (See the reference page) |
| Page | Pagenumber, 1000 candidates per page |
| Example | https://api.recman.no/v2/get/?key=YOUR_KEY&scope=candidate&fields=firstName |
Note
When doing a GET request, you must define a page number. Each page is limited to 100 candidates per page.
Let’s say you want to fetch 200 candidates from your RecMan account, you will need to perform two separated requests towards the API. Here’s an example.
1 to 100 candidates:
https://api.recman.no/v2/get/?key=YOUR_KEY&scope=candidate&fields=firstName&page=1
101 to 200 candidates
https://api.recman.no/v2/get/?key=YOUR_KEY&scope=candidate&fields=firstName&page=2
Each request will respond with a numRows value. This value will show you how many candidates the request is showing.
If requesting a page outside the number of candidates that are registered in your RecMan database, the request will respond with a numRows: 0. For instance, if you request page 3, but only have 180 candidates in your database.
PHP example on how to retrieve a list of candidates
Below you can see how a request can be done with PHP. This script will output the first 100 candidates showing only first name, last name and email. Click on the JSON reponse example to view how this script will respond.
<?php
$key = "YOUR KEY";
$scope = "candidate";
$fields = "firstName,lastName,email";
$page = 1;
$url = "https://api.recman.no/v2/get/";
$url .= "?key=$key&scope=$scope&fields=$fields&page=$page";
$response = file_get_contents($url);
print_r($response);View JSON example
{
"success": true,
"numRows": 2,
"data": {
"98385": {
"candidateId": "98385",
"corporationId": "409",
"firstName": "Johnny",
"lastName": "Appleseed",
"email": "johnny@appleseed.com"
},
"1083636": {
"candidateId": "1083636",
"corporationId": "409",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@gmail.com"
}
}
}Click here if you want to try out our API tester
Lookup on specific candidates
You can view data from a specific candidate by adding the parameter candidateId and the ID of the candidate you want to view.
This is limited to only one lookup. Here’s an example of a candidate lookup:
...&scope=candidate&fields=firstName&candidateId=982575
Look up all candidates over a certain ID
You can choose to list all candidates from a certain ID and onwards, limiting your request to candidates created after a certain time.
...&scope=candidate&fields=firstName&minCandidateId=982575
Search for candidates
You are also able to search for candidates by first name, last name and/or email. Here are some examples:
...&scope=candidate&fields=firstName&email=johnny@recman.no
Mobile Phone
...&scope=candidate&fields=firstName&mobilePhone=92808102
First Name
...&scope=candidate&fields=email&firstName=johnny
Last Name
...&scope=candidate&fields=email&lastName=appleseed
Or in combination
...&scope=candidate&fields=email&firstName=johnny&lastName=appleseed
Show candidates that has been updated after a specific date & time
Retrieve a list of all candidates that has been 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%2000:00:00
Retrieve only candidates connected to a specific department
You can view all candidates connected to a specific department by adding the parameter departmentId and the ID of the department.
...&scope=candidate&fields=firstName&departmentId=1193
Retrieving Files
When asking for the field file, you will only receive a list of file name and IDs. To be able to download files, you will need to ask for each file. By adding both candidateId and fileId as parameter.
...&scope=candidateFile&candidateId=298128&id=1245
Request only employees
You can choose to only get candidates who have the status “employee” from the system. Do accomplish this, simply add &isEmployee=1. You can also add a 0, which will result in candidates who are NOT employees.
...&scope=candidate&candidateId=298128&isEmployee=1