# List candidates

Page through candidates in a stable, curated shape. Scope: candidates:read.

Lists candidates your key can see, in the stable v1 shape. **Scope:** `candidates:read`. Visibility is organization-membership based — admins see all; employer-write members see their org's candidates; hiring managers see candidates in roles assigned to them.

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | 0-indexed page. Default `0`. |
| `pageSize` | integer | No | Rows per page (max 100). Default `20`. |
| `roleId` | string | No | Filter to candidates actively assigned to this role. |

## Example request

```bash
curl "https://app.talent-ray.com/api/v1/candidates?page=0&pageSize=20" \
  -H "Authorization: Bearer tr_YOUR_KEY"
```

## Response

`200 OK`

```json
{
  "data": [
    {
      "id": "cand_1",
      "fullName": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+905551112233",
      "status": "Active",
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-02T08:00:00Z",
      "roles": [
        { "roleId": "role_eng_be", "roleName": "Senior Backend Engineer", "organizationId": "org_acme", "status": "In Pipeline", "overallFitScore": 82, "approved": false }
      ]
    }
  ],
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 134, "totalPages": 7 }
}
```

`overallFitScore` is `-1` until an assessment has been scored, then `0–100`.

## Status codes

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `401` | No valid API key. |
| `403` | `insufficient_scope` — the key lacks `candidates:read`. |
| `429` | Rate limit exceeded. |