List candidates in your CRM
The candidates you own in your Paraform CRM, mainly to find the candidateId that other endpoints take. Only your own candidates are ever returned: candidates held by your agency teammates or by an agency owner are never included, even when your agency shares candidates in the app.
Filters are optional and combine with AND. query is a free-text search across the candidate’s name, headline, location and employer names, so use it for location questions too. linkedinUrl and email find one specific person: linkedinUrl must be the candidate’s profile link, linkedin.com/in/<handle>, with or without https:// and www., a trailing slash or a query string, in any casing (other LinkedIn links return 400 invalid_linkedin_url), and email is an exact, case-insensitive match on an email you can see for the candidate. Neither matching returns an empty list, not an error. tags and relationshipStatus match ANY of the values given; pass a filter more than once to send several values.
furthestStatus is the furthest pipeline status any of the candidate’s applications reached (SUBMITTED, INTERVIEWING, OFFER, HIRED and so on), null for a candidate you have never submitted. relationshipStatus is your working relationship with them, separate from any application.
Rows come newest first. When query is set, candidates whose name matches it come first, then the rest, newest first within each group. A page holds at most 50 candidates. Pass nextCursor back as cursor for the next page. Hidden and archived candidates are left out.
Required scopes: candidates:read.
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/candidates \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/candidates"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://external-api.paraform.com/api/external/v1/recruiter/candidates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://external-api.paraform.com/api/external/v1/recruiter/candidates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://external-api.paraform.com/api/external/v1/recruiter/candidates"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://external-api.paraform.com/api/external/v1/recruiter/candidates")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/candidates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"candidates": [
{
"candidateId": "<string>",
"name": "<string>",
"linkedinUrl": "<string>",
"location": "<string>",
"oneLiner": "<string>",
"currentRole": {
"company": "<string>",
"title": "<string>"
},
"relationshipStatus": "<string>",
"furthestStatus": "<string>",
"tags": [
"<string>"
],
"addedAt": "<string>"
}
],
"nextCursor": 123
}Authorizations
Query Parameters
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/candidates \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/candidates"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://external-api.paraform.com/api/external/v1/recruiter/candidates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://external-api.paraform.com/api/external/v1/recruiter/candidates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://external-api.paraform.com/api/external/v1/recruiter/candidates"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://external-api.paraform.com/api/external/v1/recruiter/candidates")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/candidates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"candidates": [
{
"candidateId": "<string>",
"name": "<string>",
"linkedinUrl": "<string>",
"location": "<string>",
"oneLiner": "<string>",
"currentRole": {
"company": "<string>",
"title": "<string>"
},
"relationshipStatus": "<string>",
"furthestStatus": "<string>",
"tags": [
"<string>"
],
"addedAt": "<string>"
}
],
"nextCursor": 123
}