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

# List candidates in your CRM

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

The candidates the calling recruiter owns in their Paraform CRM. An agency owner, or a member of an agency that shares candidates between members, sees more candidates in the app than this endpoint returns. Only your own candidates are ever returned; there is no parameter for reading another recruiter's CRM, so never ask the user for an id.

Filters are optional and combine with AND. `query` is a free-text search across the candidate's name, headline, location and employer names, so use it for location questions too. `tags` and `relationshipStatus` match ANY of the values given; pass a filter more than once to send several values.

`furthestStatus` is the furthest pipeline status any of the candidate's applications reached (SUBMITTED, INTERVIEWING, OFFER, HIRED and so on), null for a candidate you have never submitted. `relationshipStatus` is your working relationship with them, separate from any application.

Rows come newest first. When `query` is set, candidates whose name matches it come first, then the rest, newest first within each group. A page holds at most 50 candidates (`limit`, default 20). Pass `nextCursor` back as `cursor` for the next page. Hidden and archived candidates are left out.

## Query parameters

<ParamField query="query" type="string">
  Constraints: min length 1.
</ParamField>

<ParamField query="cursor" type="integer | null" default={"0"}>
  Constraints: minimum 0.
</ParamField>

<ParamField query="limit" type="integer" default={"20"}>
  Constraints: minimum 1.
</ParamField>

<ParamField query="tags" type="string | string[]" />

<ParamField query="relationshipStatus" type="string | string[]">
  Allowed values: `SOURCED`, `CONTACTED`, `REPLIED`, `SCHEDULED_CALL`, `SCREENED`, `ACTIVE`, `STAY_IN_TOUCH`, `BACKBURNER`.
</ParamField>

## Response

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

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

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

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

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

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

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

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

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

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

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

<ResponseField name="nextCursor" type="number" />

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/candidates?cursor=0&limit=20" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "candidateId": "string",
        "name": "string",
        "linkedinUrl": "string",
        "location": "string",
        "oneLiner": "string",
        "currentRole": {
          "company": "string",
          "title": "string"
        },
        "relationshipStatus": "string",
        "furthestStatus": "string",
        "tags": [
          "string"
        ],
        "addedAt": "string"
      }
    ]
  }
  ```
</ResponseExample>


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