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

# Candidates

> Manage candidates in your organization

# Candidates

Candidates are the people being assessed. A candidate can have multiple sessions across different assessments.

## List Candidates

```
GET /api/candidates
```

<ParamField query="limit" type="integer" default="20">
  Results per page (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Offset for pagination
</ParamField>

<ParamField query="assessmentId" type="string">
  Filter to candidates who have sessions on this assessment
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.trygradient.ai/api/candidates?assessmentId=ASSESSMENT_ID" \
    -H "Authorization: Bearer gai_your_key"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `https://app.trygradient.ai/api/candidates?assessmentId=${assessmentId}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  const { candidates, total } = await res.json();
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "candidates": [
      {
        "id": "uuid",
        "orgId": "uuid",
        "email": "jane@example.com",
        "name": "Jane Smith",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ],
    "total": 12,
    "limit": 20,
    "offset": 0
  }
  ```
</Accordion>

***

## Update Candidate

```
PATCH /api/candidates/:id
```

<ParamField body="name" type="string">
  Updated name
</ParamField>

<ParamField body="email" type="string">
  Updated email address
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "candidate": {
      "id": "uuid",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  }
  ```
</Accordion>

***

## Delete Candidate

```
DELETE /api/candidates/:id
```

Soft-deletes the candidate (sets `deleted_at` timestamp). The candidate will no longer appear in list results but their session history is preserved.

<Accordion title="Response">
  ```json theme={null}
  {
    "ok": true
  }
  ```
</Accordion>