> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paraform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles recommended for one of your candidates

<Info>
  **Required scopes:** `candidates:read`, `roles:read`<br />
  **Rate limit:** `default` tier, 120 requests per minute per key
</Info>

Paraform's own matching for a specific candidate: the roles it recommends you submit them to, strongest first.

Use this whenever the recruiter has a candidate in mind. Do NOT answer "which roles suit this person" by calling `listRecruiterRoles` 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

<ParamField path="candidateId" type="string" required>
  Constraints: min length 1.
</ParamField>

## Response

<ResponseField name="candidateId" type="string" required />

<ResponseField name="roles" type="object[]" required>
  <Expandable title="roles properties">
    <ResponseField name="id" type="string" required />

    <ResponseField name="name" type="string" required />

    <ResponseField name="postedAt" type="string | null" required />

    <ResponseField name="urls" type="object" required>
      <Expandable title="urls properties">
        <ResponseField name="browse" type="string" required />

        <ResponseField name="recruit" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="company" type="object" required>
      <Expandable title="company properties">
        <ResponseField name="name" type="string" required />

        <ResponseField name="confidentialSearch" type="boolean" required />

        <ResponseField name="anonymizedName" type="string | null" required />

        <ResponseField name="oneLiner" type="string | null" required />

        <ResponseField name="industries" type="string[]" required />

        <ResponseField name="size" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="locations" type="string[]" required />

    <ResponseField name="workplaceType" type="string | null" required />

    <ResponseField name="roleTypes" type="string[]" required />

    <ResponseField name="techStack" type="string[]" required />

    <ResponseField name="visaText" type="string | null" required />

    <ResponseField name="compensation" type="object" required>
      <Expandable title="compensation properties">
        <ResponseField name="salaryLowerBound" type="number" required />

        <ResponseField name="salaryUpperBound" type="number" required />

        <ResponseField name="currency" type="string | null" required />

        <ResponseField name="equity" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="experience" type="object" required>
      <Expandable title="experience properties">
        <ResponseField name="yearsMin" type="number" required />

        <ResponseField name="yearsMax" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="fee" type="object" required>
      <Expandable title="fee properties">
        <ResponseField name="amountLowerBound" type="number | null" required />

        <ResponseField name="percentOfSalary" type="number | null" required />

        <ResponseField name="boostPercent" type="number | null" required />

        <ResponseField name="bonusAmount" type="number | null" required />

        <ResponseField name="firstSubmissionReward" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="pipeline" type="object" required>
      <Expandable title="pipeline properties">
        <ResponseField name="totalApplications" type="number | null" required />

        <ResponseField name="totalInterviewing" type="number" required />

        <ResponseField name="totalHired" type="number" required />

        <ResponseField name="openingsText" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="myRole" type="object" required>
      <Expandable title="myRole properties">
        <ResponseField name="isApproved" type="boolean" required />

        <ResponseField name="isPrimary" type="boolean" required />

        <ResponseField name="accessLevel" type="string | null" required />

        <ResponseField name="approvalStatus" type="string | null" required />

        <ResponseField name="submissions" type="object" required>
          <Expandable title="submissions properties">
            <ResponseField name="submitted" type="number" required />

            <ResponseField name="interviewing" type="number" required />

            <ResponseField name="hired" type="number" required />

            <ResponseField name="total" type="number" required />
          </Expandable>
        </ResponseField>

        <ResponseField name="trial" type="object | null" required>
          <Expandable title="trial properties">
            <ResponseField name="endsAt" type="string | null" required />

            <ResponseField name="businessDaysLeft" type="number | null" required />

            <ResponseField name="submissionGoal" type="number" required />

            <ResponseField name="submissionsCounted" type="number" required />

            <ResponseField name="isActive" type="boolean" required />

            <ResponseField name="endingSoon" type="boolean" required />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recruiterAccess" type="object" required>
      <Expandable title="recruiterAccess properties">
        <ResponseField name="atMaxCapacity" type="boolean" required />

        <ResponseField name="notAcceptingRecruiters" type="boolean" required />

        <ResponseField name="density" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="hiringManager" type="object" required>
      <Expandable title="hiringManager properties">
        <ResponseField name="lastActiveAt" type="string | null" required />

        <ResponseField name="responsivenessDays" type="number" required />

        <ResponseField name="engagement" type="object | null" required>
          <Expandable title="engagement properties">
            <ResponseField name="finalRating" type="number | null" required />

            <ResponseField name="percentileRank" type="number | null" required />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recommendation" type="object" required>
      <Expandable title="recommendation properties">
        <ResponseField name="band" type="string" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/candidates/$CANDIDATE_ID/recommended-roles" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.