> ## 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.

# Candidates and recommended roles

> Read your CRM candidates and the roles Paraform recommends for them.

## List your candidates

[`GET /recruiter/candidates`](/recruiter/api-reference/list-recruiter-candidates) (`candidates:read`) returns the candidates **you own** in your Paraform CRM, newest first. Hidden and archived candidates are left out.

```bash theme={null}
curl -G "https://external-api.paraform.com/api/external/v1/recruiter/candidates" \
  -H "Authorization: Bearer $PARAFORM_API_KEY" \
  --data-urlencode "query=Austin"
```

| Parameter | Use |
| - | - |
| `query` | Free-text search over name, headline, location, and employers. Name matches come first. |
| `tags`, `relationshipStatus` | Match any of the values given. Repeat the parameter to send several. |
| `limit`, `cursor` | Default 20, maximum 50. See [Pagination](/pagination). |

Each candidate has `furthestStatus`, the furthest pipeline status any of their applications reached (for example `SUBMITTED`, `INTERVIEWING`, `OFFER`, or `HIRED`), or `null` if you've never submitted them. `relationshipStatus` is your working relationship with them, separate from any application.

<Note>
  Agency owners, and members of agencies that share candidates, see more candidates in the app than this endpoint returns. The API only returns candidates you own.
</Note>

## Roles recommended for one candidate

[`GET /recruiter/candidates/{candidateId}/recommended-roles`](/recruiter/api-reference/list-recommended-roles-for-candidate) (`candidates:read` and `roles:read`) returns the roles Paraform's matching recommends for a specific candidate, strongest first. `candidateId` is the `candidateId` from the candidate list.

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

* `recommendation.band` is `ENDORSED` (a strong match) or `SUGGESTED` (worth a look).
* Each role carries the same fields as [`GET /recruiter/roles`](/recruiter/guides/browse-roles), including `myRole` and `fee`.
* The list is short by design, at most about 15 roles. It already leaves out roles the candidate was submitted to and roles Paraform is still assessing.
* An empty list means no recommendations were found for this candidate right now.

Use this endpoint whenever a particular candidate is in mind, rather than filtering `GET /recruiter/roles` yourself. It's backed by Paraform's matching model, which reads the candidate's full profile.

## Recommendations across your whole CRM

[`GET /recruiter/recommendations`](/recruiter/api-reference/list-recruiter-recommendations) (`candidates:read` and `roles:read`) returns the **Recommended submissions** list from your Paraform home page: the roles recommended for every candidate in your CRM.

```bash theme={null}
curl "https://external-api.paraform.com/api/external/v1/recruiter/recommendations" \
  -H "Authorization: Bearer $PARAFORM_API_KEY"
```

* Returns at most 20 (candidate, role) pairs, strongest first. `ENDORSED` pairs come before `SUGGESTED` ones.
* Candidates are ordered by their strongest pair, and each candidate's roles strongest first.
* Already leaves out recently hired candidates, roles a candidate was already submitted to, and roles you can't submit to.
* `enabled` tells you whether recommendations are on for your account. An empty list with `enabled: true` means there are no active recommendations right now.

For one named candidate, use the per-candidate endpoint above instead. Don't loop it over your whole CRM, because this call returns the same rows in one request.


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