ParaAI matches sent to you by hiring managers
ParaAI matches sent to you: a hiring manager looked at a candidate profile, asked for that specific candidate on a specific role, and Paraform routed the request to you because the candidate is in your CRM. This is a different list from listRecommendedRolesForCandidate, where Paraform’s model suggests roles; here a person asked.
Each row carries the hiring manager’s name and their note on why they want the candidate, the role with its pay and your fee, the candidate, and the deadline. A pending match expires 7 days after it is sent (daysUntilExpiry), and unresolved expired matches can pause ParaAI matching for you, so the oldest pending rows are the most urgent.
actionBucket says what to do: new means nobody has contacted the candidate, needs_submission means you marked them contacted but have not submitted, expired means the window closed, closed means submitted or passed.
status narrows the list: pending (default), expired, dismissed, submitted, or all. Pending matches on closed roles are left out; resolved matches are kept. Rows come back oldest first. A page holds at most 20 matches. Pass nextCursor back as cursor, with the same status, for the next page; nextCursor is absent on the last page. The cursor marks a position, so acting on a match between pages does not skip or repeat rows.
role.feePercent is null when your agency hides payment from its members; agency owners always see it. role.urls.recruit is null until you are approved on the role.
When role.company.confidentialSearch is true the search is confidential: candidate-facing copy must refer to the employer as role.company.anonymizedName and must not name the company or quote copy that identifies it.
This endpoint is read-only; contacting, passing and submitting happen in the Paraform app.
Required scopes: candidates:read, roles:read, submissions:read.
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations"
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/paraai-recommendations', 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/paraai-recommendations",
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/paraai-recommendations"
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/paraai-recommendations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations")
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{
"recommendations": [
{
"id": "<string>",
"status": "<string>",
"actionBucket": "new",
"sentAt": "<string>",
"daysUntilExpiry": 123,
"reachedOutToCandidate": true,
"hiringManagerNote": "<string>",
"hiringManagerName": "<string>",
"candidate": {
"candidateId": "<string>",
"name": "<string>",
"title": "<string>",
"oneLiner": "<string>",
"location": "<string>",
"linkedinUrl": "<string>"
},
"role": {
"id": "<string>",
"name": "<string>",
"urls": {
"browse": "<string>",
"recruit": "<string>"
},
"locations": [
"<string>"
],
"company": {
"name": "<string>",
"confidentialSearch": true,
"anonymizedName": "<string>"
},
"compensation": {
"salaryLowerBound": 123,
"salaryUpperBound": 123,
"currency": "<string>"
},
"feePercent": 123
},
"application": {
"progressLabel": "<string>",
"rejectedAfterStage": "<string>"
}
}
],
"nextCursor": "<string>"
}Authorizations
Query Parameters
curl --request GET \
--url https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations \
--header 'Authorization: Bearer <token>'import requests
url = "https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations"
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/paraai-recommendations', 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/paraai-recommendations",
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/paraai-recommendations"
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/paraai-recommendations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://external-api.paraform.com/api/external/v1/recruiter/paraai-recommendations")
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{
"recommendations": [
{
"id": "<string>",
"status": "<string>",
"actionBucket": "new",
"sentAt": "<string>",
"daysUntilExpiry": 123,
"reachedOutToCandidate": true,
"hiringManagerNote": "<string>",
"hiringManagerName": "<string>",
"candidate": {
"candidateId": "<string>",
"name": "<string>",
"title": "<string>",
"oneLiner": "<string>",
"location": "<string>",
"linkedinUrl": "<string>"
},
"role": {
"id": "<string>",
"name": "<string>",
"urls": {
"browse": "<string>",
"recruit": "<string>"
},
"locations": [
"<string>"
],
"company": {
"name": "<string>",
"confidentialSearch": true,
"anonymizedName": "<string>"
},
"compensation": {
"salaryLowerBound": 123,
"salaryUpperBound": 123,
"currency": "<string>"
},
"feePercent": 123
},
"application": {
"progressLabel": "<string>",
"rejectedAfterStage": "<string>"
}
}
],
"nextCursor": "<string>"
}