# List potential candidates

Page through sourced/CV-screened leads. Scope: sourcing:read.

Lists potential candidates — sourced or CV-screened **leads** that exist before a candidate creates an account. **Scope:** `sourcing:read`. Visibility: admins all; everyone else sees leads linked to an organization they belong to.

## 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 leads linked to this role. |
| `status` | string | No | Filter by lead status. |

## Example request

```bash
curl "https://app.talent-ray.com/api/v1/sourcing?status=parsed" \
  -H "Authorization: Bearer tr_YOUR_KEY"
```

## Response

`200 OK`

```json
{
  "data": [
    {
      "id": "pc_1",
      "fullName": "Sam Lee",
      "email": "sam.cv@example.com",
      "contactEmail": "sam@example.com",
      "phone": "+905559998877",
      "status": "parsed",
      "skills": ["python", "sql"],
      "summary": "5y data engineering.",
      "candidateId": null,
      "organizations": [ { "organizationId": "org_acme", "status": "Pool" } ],
      "roles": [
        { "roleId": "role_eng_be", "roleName": "Senior Backend Engineer", "organizationId": "org_acme", "status": "Assigned", "resumeFitScore": 71, "overallFitScore": -1 }
      ],
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-01T10:30:00Z"
    }
  ],
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 60, "totalPages": 3 }
}
```

`email` is parsed from the CV; `contactEmail` is the account email used for invitations. `candidateId` is set once the lead is converted into a candidate. Fit scores are `-1` until screened/scored.

## Status codes

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