Bulk Invite Candidates

When you’re assessing multiple candidates, you can automate invitations using the API and a simple script.

Prerequisites

An API key with admin access
An existing assessment ID

Basic bulk invite

Loop through a list of candidates and invite each one:

API_KEY="gai_your_key"
ASSESSMENT_ID="your-assessment-id"

# Invite from a list
for email in alice@company.com bob@company.com carol@company.com; do
  name=$(echo "$email" | cut -d@ -f1 | sed 's/\./ /g')
  curl -s -X POST "https://app.trygradient.ai/api/assessments/$ASSESSMENT_ID/invite" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"name\": \"$name\"}" | jq '.inviteUrl'
done

const API_KEY = 'gai_your_key';
const ASSESSMENT_ID = 'your-assessment-id';

const candidates = [
  { email: 'alice@company.com', name: 'Alice Johnson' },
  { email: 'bob@company.com', name: 'Bob Smith' },
  { email: 'carol@company.com', name: 'Carol Davis' },
];

for (const candidate of candidates) {
  const res = await fetch(
    `https://app.trygradient.ai/api/assessments/${ASSESSMENT_ID}/invite`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(candidate),
    }
  );
  const data = await res.json();
  console.log(`${candidate.email}: ${data.inviteUrl}`);
}

import requests

API_KEY = "gai_your_key"
ASSESSMENT_ID = "your-assessment-id"

candidates = [
    {"email": "alice@company.com", "name": "Alice Johnson"},
    {"email": "bob@company.com", "name": "Bob Smith"},
    {"email": "carol@company.com", "name": "Carol Davis"},
]

for candidate in candidates:
    res = requests.post(
        f"https://app.trygradient.ai/api/assessments/{ASSESSMENT_ID}/invite",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=candidate,
    )
    data = res.json()
    print(f"{candidate['email']}: {data.get('inviteUrl')}")

Invite from CSV

For larger batches, read candidates from a CSV file:

API_KEY="gai_your_key"
ASSESSMENT_ID="your-assessment-id"

# CSV format: name,email
tail -n +2 candidates.csv | while IFS=, read -r name email; do
  curl -s -X POST "https://app.trygradient.ai/api/assessments/$ASSESSMENT_ID/invite" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"name\": \"$name\"}"
  echo ""
done

Handling duplicates

The invite endpoint is idempotent - if a candidate already has an active session for the assessment, it returns the existing session with a 200 OK instead of creating a new one. This means you can safely re-run your invite script without creating duplicate sessions.

Setting per-candidate deadlines

You can set individual deadlines that override the assessment-level due date:

curl -X POST "https://app.trygradient.ai/api/assessments/$ASSESSMENT_ID/invite" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@company.com",
    "name": "Alice Johnson",
    "dueDate": "2026-12-01T23:59:59Z"
  }'

Monitoring progress

After inviting candidates, poll for session status to track who has completed:

# List all sessions for this assessment
curl "https://app.trygradient.ai/api/sessions?assessmentId=$ASSESSMENT_ID" \
  -H "Authorization: Bearer $API_KEY" | jq '.sessions[] | {name: .candidateName, status: .status}'

​Bulk Invite Candidates

​Prerequisites

​Basic bulk invite

​Invite from CSV

​Handling duplicates

​Setting per-candidate deadlines

​Monitoring progress