Candidates

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

List Candidates

GET /api/candidates

limit

integer

default:"20"

Results per page (1-100)

offset

integer

default:"0"

Offset for pagination

assessmentId

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

name

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 deleted_at timestamp). The candidate will no longer appear in list results but their session history is preserved.

Response

{
  "ok": true
}

Assessments Sessions

​Candidates

​List Candidates

​Update Candidate

​Delete Candidate

Candidates

List Candidates

Update Candidate

Delete Candidate