Schedule Interviews | Gradii API Documentation

curl -X POST https://gradii.ai/api/v2/interviews/schedule \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "campaignId": "123e4567-e89b-12d3-a456-426614174000",
  "candidateName": "John Doe",
  "candidateEmail": "john@example.com",
  "interviewDate": "2024-02-15",
  "interviewTime": "10:00",
  "roundNumber": 1,
  "candidatePhone": 1234567890,
  "candidateCountryCode": "+1",
  "timezone": "Asia/Kolkata",
  "notes": "Technical interview for senior developer role"
}'

{
  "success": true,
  "data": {
    "id": "db-id-123",
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "candidateId": "cand_789",
    "setupId": "setup_456",
    "interviewId": "interview_abc123_candidateId_1234567890",
    "interviewType": "behavioral",
    "status": "scheduled",
    "roundOrder": 1,
    "scheduledAt": "2024-02-15T04:30:00.000Z",
    "timezone": "Asia/Kolkata",
    "linkExpiryTime": "2024-02-16T04:30:00.000Z",
    "interviewLink": "https://gradii.ai/interview/verify?email=john@example.com&interviewId=interview_abc123&type=behavioral",
    "candidateNotes": "Technical interview for senior developer role",
    "createdAt": "2024-01-28T10:00:00.000Z",
    "updatedAt": "2024-01-28T10:00:00.000Z",
    "campaignName": "Senior Developer Hiring",
    "jobTitle": "Senior Software Engineer",
    "candidateName": "John Doe",
    "candidateEmail": "john@example.com",
    "candidatePhone": "+11234567890",
    "setupRoundName": "Technical Round",
    "setupInterviewType": "behavioral",
    "isNewCandidate": true,
    "emailSent": true
  },
  "message": "Interview scheduled successfully",
  "timestamp": "2024-01-28T10:00:00Z",
  "version": "2.0"
}

Schedule single or multiple interviews with automatic email notifications. Creates candidate if not exists.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

campaignIdstringRequiredformat: "uuid"

Campaign ID

candidateNamestringRequired

Candidate full name (1-100 chars)

candidateEmailstringRequiredformat: "email"

Valid email address (lowercase)

interviewDatestringRequired

Date in YYYY-MM-DD format

interviewTimestringRequired

Time in HH:MM or HH:MM:SS format

roundNumberintegerRequired

Round number (1-10), must exist in campaign setup

candidatePhonedoubleOptional

Phone number (max 30 chars)

candidateCountryCodestringOptional

Country code (e.g., +1)

timezonestringOptional

Timezone (default: Asia/Kolkata)

notesstringOptional

Additional notes (max 500 chars)

Response

Interview scheduled successfully (single)

successbooleanOptional

dataobjectOptional

messagestringOptional

timestampstringOptional

versionstringOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error