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

# List candidates

> Returns paginated candidates for a sourcing.

<Card title="First time? Set up Authentication" icon="key" href="/authentication">
  Learn how to authenticate your API requests with your API key.
</Card>

Returns candidates for a sourcing using the same pagination, filters, and ordering as the Kalent candidates table.

## Path parameters

<ParamField path="sourcingId" type="string" required>
  Sourcing id in the authenticated workspace.
</ParamField>

## Query parameters

<ParamField query="pageIndex" type="integer" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="pageSize" type="integer" default="25">
  Page size (max 50).
</ParamField>

<ParamField query="search" type="string">
  Free-text search on candidate/talent fields.
</ParamField>

<ParamField query="statusHandle" type="string">
  Repeatable status filter. When omitted, defaults to all statuses except `NOT_RETAINED`.
</ParamField>

<ParamField query="location" type="string">
  Repeatable city filter.
</ParamField>

<ParamField query="jobTitle" type="string">
  Repeatable job title filter.
</ParamField>

<ParamField query="currentCompany" type="string">
  Repeatable current company filter.
</ParamField>

<ParamField query="sortField" type="string">
  One of `name`, `companyName`, `statusHandle`, `city`, `jobTitle`, `userRating`, `contacts`, `createdAt`, `history`.
</ParamField>

<ParamField query="sortOrder" type="string">
  `asc` or `desc`.
</ParamField>

## Response

When `success` is `true`, `data` contains:

* `candidates` — list of `{ candidate, talent }` summaries:
  * `candidate.id`
  * `candidate.statusHandle`
  * `candidate.createdAt`
  * `candidate.sourcingId`
  * `candidate.talentId`
  * `talent.id`
  * `talent.firstname`
  * `talent.lastname`
  * `talent.jobTitle`
  * `talent.city`
  * `talent.linkedinUrl`
* `pagination` — `pageIndex`, `pageSize`, `total`, `hasNextPage`

```json theme={null}
{
  "success": true,
  "data": {
    "candidates": [
      {
        "candidate": {
          "id": "candidate_123",
          "statusHandle": "TO_BE_CONTACTED",
          "createdAt": "2026-05-19T09:00:00.000Z",
          "sourcingId": "sourcing_123",
          "talentId": "talent_123"
        },
        "talent": {
          "id": "talent_123",
          "firstname": "Grace",
          "lastname": "Hopper",
          "jobTitle": "Software Engineer",
          "city": "Paris",
          "linkedinUrl": "https://www.linkedin.com/in/example"
        }
      }
    ],
    "pagination": {
      "pageIndex": 0,
      "pageSize": 25,
      "total": 1,
      "hasNextPage": false
    }
  }
}
```

## Errors

| Code               | HTTP |
| ------------------ | ---- |
| `validation_error` | 400  |
| `not_found`        | 404  |
| `internal_error`   | 500  |

```bash theme={null}
curl -G "https://app.kalent.ai/api/v1/sourcings/SOURCING_ID/candidates" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "pageIndex=0" \
  --data-urlencode "pageSize=25"
```