Recruiter
Roles recommended for one of your candidates
curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/candidates/$CANDIDATE_ID/recommended-roles" \
-H "Authorization: Bearer $PARAFORM_API_KEY"
{
"candidateId": "string",
"roles": [
{
"id": "string",
"name": "string",
"postedAt": "string",
"urls": {
"browse": "string",
"recruit": "string"
},
"company": {
"name": "string",
"confidentialSearch": true,
"anonymizedName": "string",
"oneLiner": "string",
"industries": [],
"size": 0
},
"locations": [
"string"
],
"workplaceType": "string",
"roleTypes": [
"string"
],
"techStack": [
"string"
],
"visaText": "string",
"compensation": {
"salaryLowerBound": 0,
"salaryUpperBound": 0,
"currency": "string",
"equity": "string"
},
"experience": {
"yearsMin": 0,
"yearsMax": 0
},
"fee": {
"amountLowerBound": 0,
"percentOfSalary": 0,
"boostPercent": 0,
"bonusAmount": 0,
"firstSubmissionReward": 0
},
"pipeline": {
"totalApplications": 0,
"totalInterviewing": 0,
"totalHired": 0,
"openingsText": "string"
},
"myRole": {
"isApproved": true,
"isPrimary": true,
"accessLevel": "string",
"approvalStatus": "string",
"submissions": {},
"trial": {}
},
"recruiterAccess": {
"atMaxCapacity": true,
"notAcceptingRecruiters": true,
"density": "string"
},
"hiringManager": {
"lastActiveAt": "string",
"responsivenessDays": 0,
"engagement": {}
},
"recommendation": {
"band": "string"
}
}
]
}
Required scopes:
Rate limit:
candidates:read, roles:readRate limit:
default tier, 120 requests per minute per keylistRecruiterRoles and filtering by hand: this endpoint is backed by Paraform’s matching model, which reads the candidate’s full profile and is what the in-app recommendations use. listRecruiterRoles is for finding roles to work on when no particular candidate is in play.
candidateId is the candidateId field from listRecruiterCandidates.
recommendation.band is ENDORSED (a strong match) or SUGGESTED (worth a look). Every role carries the same fields listRecruiterRoles returns, including myRole and fee.
The list is short by design, at most about 15 roles, and it already leaves out roles this candidate has been submitted to and roles Paraform is still assessing. An empty list means either that Paraform currently has no recommendation for this candidate or that recommendations are not enabled for your account; the response does not say which, so do not tell the recruiter no role fits. Fall back to listRecruiterRoles with filters drawn from what the recruiter tells you about the candidate.
Path parameters
string
required
Constraints: min length 1.
Response
string
required
object[]
required
Show roles properties
Show roles properties
string
required
string
required
string | null
required
object
required
string[]
required
string | null
required
string[]
required
string[]
required
string | null
required
object
required
object
required
object
required
object
required
Show myRole properties
Show myRole properties
boolean
required
boolean
required
string | null
required
string | null
required
object
required
object
required
object
required
curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/candidates/$CANDIDATE_ID/recommended-roles" \
-H "Authorization: Bearer $PARAFORM_API_KEY"
{
"candidateId": "string",
"roles": [
{
"id": "string",
"name": "string",
"postedAt": "string",
"urls": {
"browse": "string",
"recruit": "string"
},
"company": {
"name": "string",
"confidentialSearch": true,
"anonymizedName": "string",
"oneLiner": "string",
"industries": [],
"size": 0
},
"locations": [
"string"
],
"workplaceType": "string",
"roleTypes": [
"string"
],
"techStack": [
"string"
],
"visaText": "string",
"compensation": {
"salaryLowerBound": 0,
"salaryUpperBound": 0,
"currency": "string",
"equity": "string"
},
"experience": {
"yearsMin": 0,
"yearsMax": 0
},
"fee": {
"amountLowerBound": 0,
"percentOfSalary": 0,
"boostPercent": 0,
"bonusAmount": 0,
"firstSubmissionReward": 0
},
"pipeline": {
"totalApplications": 0,
"totalInterviewing": 0,
"totalHired": 0,
"openingsText": "string"
},
"myRole": {
"isApproved": true,
"isPrimary": true,
"accessLevel": "string",
"approvalStatus": "string",
"submissions": {},
"trial": {}
},
"recruiterAccess": {
"atMaxCapacity": true,
"notAcceptingRecruiters": true,
"density": "string"
},
"hiringManager": {
"lastActiveAt": "string",
"responsivenessDays": 0,
"engagement": {}
},
"recommendation": {
"band": "string"
}
}
]
}
⌘I
curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/candidates/$CANDIDATE_ID/recommended-roles" \
-H "Authorization: Bearer $PARAFORM_API_KEY"
{
"candidateId": "string",
"roles": [
{
"id": "string",
"name": "string",
"postedAt": "string",
"urls": {
"browse": "string",
"recruit": "string"
},
"company": {
"name": "string",
"confidentialSearch": true,
"anonymizedName": "string",
"oneLiner": "string",
"industries": [],
"size": 0
},
"locations": [
"string"
],
"workplaceType": "string",
"roleTypes": [
"string"
],
"techStack": [
"string"
],
"visaText": "string",
"compensation": {
"salaryLowerBound": 0,
"salaryUpperBound": 0,
"currency": "string",
"equity": "string"
},
"experience": {
"yearsMin": 0,
"yearsMax": 0
},
"fee": {
"amountLowerBound": 0,
"percentOfSalary": 0,
"boostPercent": 0,
"bonusAmount": 0,
"firstSubmissionReward": 0
},
"pipeline": {
"totalApplications": 0,
"totalInterviewing": 0,
"totalHired": 0,
"openingsText": "string"
},
"myRole": {
"isApproved": true,
"isPrimary": true,
"accessLevel": "string",
"approvalStatus": "string",
"submissions": {},
"trial": {}
},
"recruiterAccess": {
"atMaxCapacity": true,
"notAcceptingRecruiters": true,
"density": "string"
},
"hiringManager": {
"lastActiveAt": "string",
"responsivenessDays": 0,
"engagement": {}
},
"recommendation": {
"band": "string"
}
}
]
}