Skip to main content

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.

​
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

​
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": "2025-02-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}'