Candidates

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

List Candidates

GET /api/candidates

integer

default:"20"

Results per page (1-100)

integer

default:"0"

Offset for pagination

string

Filter to candidates who have sessions on this assessment

curl "https://app.trygradient.ai/api/candidates?assessmentId=ASSESSMENT_ID" \
  -H "Authorization: Bearer gai_your_key"

const res = await fetch(
  `https://app.trygradient.ai/api/candidates?assessmentId=${assessmentId}`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { candidates, total } = await res.json();

Response

{
  "candidates": [
    {
      "id": "uuid",
      "orgId": "uuid",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Update Candidate

PATCH /api/candidates/:id

string

Updated name

string

Updated email address

Response

{
  "candidate": {
    "id": "uuid",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Delete Candidate

DELETE /api/candidates/:id

Soft-deletes the candidate (sets the deleted_at timestamp). This is the everyday “Remove”. The candidate no longer appears in list results, but the row, the candidate PII, and all session history stay intact. The action is reversible with Restore Candidate. It is not an erasure. To erase the data permanently, use Purge Candidate.

Response

{
  "ok": true
}

Restore Candidate

POST /api/candidates/:id/restore

Restores a soft-deleted candidate from the trash back to the active lists (clears deleted_at). This is open to any org member. It fails if the candidate was permanently purged, because a purged row keeps no data to restore.

Response

{
  "candidate": {
    "id": "...",
    "name": "...",
    "email": "..."
  }
}

Purge Candidate

POST /api/candidates/:id/purge

Permanently erases the candidate and every session artifact (transcripts, scores, events, rrweb recordings, and deliverable files, plus the backing Storage objects). It then scrubs the candidate PII and keeps a PII-free tombstone row. This action is irreversible. Only owners and admins can purge (capability candidates.purge). API-key callers have no role and are refused: a machine credential cannot trigger an irreversible erasure.

Response

{
  "ok": true
}

Overview

Endpoints

Candidates

Candidates

List Candidates

Update Candidate

Delete Candidate

Restore Candidate

Purge Candidate

​Candidates

​List Candidates

​Update Candidate

​Delete Candidate

​Restore Candidate

​Purge Candidate

Candidates

List Candidates

Update Candidate

Delete Candidate

Restore Candidate

Purge Candidate