Roles recommended for one of your candidates
Paraform’s own matching for a specific candidate: the roles it recommends you submit them to, strongest first, each with the reasoning behind it.
This is the tool for “which roles suit this person” when the recruiter has a candidate in mind. Matching reads the candidate’s full profile. listRecruiterRoles is for finding roles to work on when no particular candidate is in play.
candidateId is the candidateId field from listRecruiterCandidates. The candidate must be in your own CRM: any other id, including a teammate’s, answers 404.
status is ready or generating. generating means Paraform is building this candidate’s recommendations now: roles is empty, and you should repeat the same request after retryAfterSeconds (about 15 to 30 seconds). Repeating it is safe. ready with an empty roles array means generation finished and no available recommendations could be found for the candidate. That does not mean no role could ever fit: listRecruiterRoles with filters drawn from what is known about the candidate is the fallback. Stored recommendations are served as they are and refreshed in the background once they are about a week old. A null status means Paraform cannot recommend roles for this candidate right now: roles is empty and message says why (a missing resume or job preferences, an unreadable resume, a candidate Paraform does not recommend for, or generation failing repeatedly in the last day), naming what to fix on the Candidates page when the recruiter can. Repeating the request soon does not change it.
recommendation.band is ENDORSED (a strong match) or SUGGESTED (worth a look). Every role carries the same fields listRecruiterRoles returns, including myRole and fee, and only roles you could see and submit this candidate to are listed. fee amounts are null field by field for members of an agency whose owner hides payment details; null means hidden, not zero. The list is short by design, at most 20 roles.
recommendation.fit is the reasoning: the verdict (rating and its label), a summary paragraph, and per-requirement assessments with their reasoning and evidence from the candidate’s profile. complete is false while parts of the analysis are still being written, and fit is null when no saved analysis exists yet; the role is still a valid recommendation and a later request can fill it in.
404, carrying details.candidatesUrl (the Candidates page), means the candidate is not in your CRM.
Required scopes: candidates:read, roles:read.
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles"
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/{candidateId}/recommended-roles', 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/{candidateId}/recommended-roles",
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/{candidateId}/recommended-roles"
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/{candidateId}/recommended-roles")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles")
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{
"candidateId": "<string>",
"status": "ready",
"roles": [
{
"id": "<string>",
"name": "<string>",
"postedAt": "<string>",
"urls": {
"browse": "<string>",
"recruit": "<string>"
},
"company": {
"name": "<string>",
"confidentialSearch": true,
"anonymizedName": "<string>",
"oneLiner": "<string>",
"industries": [
"<string>"
],
"size": 123
},
"locations": [
"<string>"
],
"workplaceType": "<string>",
"roleTypes": [
"<string>"
],
"techStack": [
"<string>"
],
"visaText": "<string>",
"compensation": {
"salaryLowerBound": 123,
"salaryUpperBound": 123,
"currency": "<string>",
"equity": "<string>"
},
"experience": {
"yearsMin": 123,
"yearsMax": 123
},
"fee": {
"amountLowerBound": 123,
"percentOfSalary": 123,
"boostPercent": 123,
"bonusAmount": 123,
"firstSubmissionReward": 123
},
"pipeline": {
"totalApplications": 123,
"totalInterviewing": 123,
"totalHired": 123,
"openingsText": "<string>"
},
"myRole": {
"isApproved": true,
"isPrimary": true,
"accessLevel": "<string>",
"approvalStatus": "<string>",
"submissions": {
"submitted": 123,
"interviewing": 123,
"hired": 123,
"total": 123
},
"trial": {
"endsAt": "<string>",
"businessDaysLeft": 123,
"submissionGoal": 123,
"submissionsCounted": 123,
"isActive": true,
"endingSoon": true
}
},
"recruiterAccess": {
"atMaxCapacity": true,
"notAcceptingRecruiters": true,
"density": "<string>"
},
"hiringManager": {
"lastActiveAt": "<string>",
"responsivenessDays": 123,
"engagement": {
"finalRating": 123,
"percentileRank": 123
}
},
"recommendation": {
"band": "<string>",
"fit": {
"rating": "GOOD_FIT",
"label": "<string>",
"summary": "<string>",
"complete": true,
"requirements": [
{
"description": "<string>",
"importance": "DEALBREAKER",
"assessment": "GOOD_FIT",
"reasoning": "<string>",
"candidateEvidence": [
"<string>"
]
}
]
}
}
}
],
"message": "<string>",
"retryAfterSeconds": 123
}Authorizations
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles"
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/{candidateId}/recommended-roles', 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/{candidateId}/recommended-roles",
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/{candidateId}/recommended-roles"
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/{candidateId}/recommended-roles")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/candidates/{candidateId}/recommended-roles")
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{
"candidateId": "<string>",
"status": "ready",
"roles": [
{
"id": "<string>",
"name": "<string>",
"postedAt": "<string>",
"urls": {
"browse": "<string>",
"recruit": "<string>"
},
"company": {
"name": "<string>",
"confidentialSearch": true,
"anonymizedName": "<string>",
"oneLiner": "<string>",
"industries": [
"<string>"
],
"size": 123
},
"locations": [
"<string>"
],
"workplaceType": "<string>",
"roleTypes": [
"<string>"
],
"techStack": [
"<string>"
],
"visaText": "<string>",
"compensation": {
"salaryLowerBound": 123,
"salaryUpperBound": 123,
"currency": "<string>",
"equity": "<string>"
},
"experience": {
"yearsMin": 123,
"yearsMax": 123
},
"fee": {
"amountLowerBound": 123,
"percentOfSalary": 123,
"boostPercent": 123,
"bonusAmount": 123,
"firstSubmissionReward": 123
},
"pipeline": {
"totalApplications": 123,
"totalInterviewing": 123,
"totalHired": 123,
"openingsText": "<string>"
},
"myRole": {
"isApproved": true,
"isPrimary": true,
"accessLevel": "<string>",
"approvalStatus": "<string>",
"submissions": {
"submitted": 123,
"interviewing": 123,
"hired": 123,
"total": 123
},
"trial": {
"endsAt": "<string>",
"businessDaysLeft": 123,
"submissionGoal": 123,
"submissionsCounted": 123,
"isActive": true,
"endingSoon": true
}
},
"recruiterAccess": {
"atMaxCapacity": true,
"notAcceptingRecruiters": true,
"density": "<string>"
},
"hiringManager": {
"lastActiveAt": "<string>",
"responsivenessDays": 123,
"engagement": {
"finalRating": 123,
"percentileRank": 123
}
},
"recommendation": {
"band": "<string>",
"fit": {
"rating": "GOOD_FIT",
"label": "<string>",
"summary": "<string>",
"complete": true,
"requirements": [
{
"description": "<string>",
"importance": "DEALBREAKER",
"assessment": "GOOD_FIT",
"reasoning": "<string>",
"candidateEvidence": [
"<string>"
]
}
]
}
}
}
],
"message": "<string>",
"retryAfterSeconds": 123
}