Skip to main content
curl -X POST "https://backend.jobhive.ai/v1/interviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_email": "[email protected]",
    "position": "Full Stack Developer",
    "skills": ["JavaScript", "React", "Node.js", "PostgreSQL"],
    "duration_minutes": 45,
    "difficulty": "intermediate",
    "company_name": "TechCorp Inc",
    "instructions": "Focus on React hooks and database design patterns"
  }'

{
  "success": true,
  "data": {
    "id": "int_abc123def456",
    "status": "scheduled",
    "candidate_email": "[email protected]",
    "position": "Full Stack Developer",
    "interview_url": "https://app.jobhive.ai/interview/int_abc123def456",
    "scheduled_at": "2024-01-15T15:30:00Z",
    "estimated_duration": 45,
    "skills": ["JavaScript", "React", "Node.js", "PostgreSQL"],
    "difficulty": "intermediate",
    "company_name": "TechCorp Inc",
    "created_at": "2024-01-15T14:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T14:30:00Z",
    "request_id": "req_create_int_001"
  }
}
Creates a new interview session for a candidate. This endpoint schedules an AI-powered interview with customizable parameters including skills assessment, duration, and difficulty level.

​
Request Body

​
candidate_email
string
required
Email address of the candidate to be interviewed
​
position
string
required
Job position or role title for the interview
​
skills
array
required
Array of skills to assess during the interview
​
duration_minutes
integer
default:"30"
Interview duration in minutes (15-90 minutes)
​
difficulty
string
default:"intermediate"
Interview difficulty level
​
company_name
string
Company name to personalize the interview experience
​
instructions
string
Custom instructions or focus areas for the AI interviewer
​
send_invitation
boolean
default:"true"
Whether to automatically send interview invitation to candidate
​
scheduled_at
string
ISO 8601 timestamp to schedule interview for future date/time
​
test_mode
boolean
default:"false"
Enable test mode to avoid consuming production credits

​
Response

​
id
string
Unique interview identifier
​
status
string
Current interview status: scheduled, in_progress, completed, cancelled
​
candidate_email
string
Email address of the candidate
​
position
string
Job position for the interview
​
interview_url
string
Direct URL for candidate to join the interview
​
scheduled_at
string
ISO 8601 timestamp when interview is scheduled
​
estimated_duration
integer
Estimated interview duration in minutes
​
skills
array
Array of skills to be assessed
​
created_at
string
ISO 8601 timestamp when interview was created

​
Examples

curl -X POST "https://backend.jobhive.ai/v1/interviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_email": "[email protected]",
    "position": "Full Stack Developer",
    "skills": ["JavaScript", "React", "Node.js", "PostgreSQL"],
    "duration_minutes": 45,
    "difficulty": "intermediate",
    "company_name": "TechCorp Inc",
    "instructions": "Focus on React hooks and database design patterns"
  }'

{
  "success": true,
  "data": {
    "id": "int_abc123def456",
    "status": "scheduled",
    "candidate_email": "[email protected]",
    "position": "Full Stack Developer",
    "interview_url": "https://app.jobhive.ai/interview/int_abc123def456",
    "scheduled_at": "2024-01-15T15:30:00Z",
    "estimated_duration": 45,
    "skills": ["JavaScript", "React", "Node.js", "PostgreSQL"],
    "difficulty": "intermediate",
    "company_name": "TechCorp Inc",
    "created_at": "2024-01-15T14:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T14:30:00Z",
    "request_id": "req_create_int_001"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "candidate_email": "Invalid email format",
      "duration_minutes": "Must be between 15 and 90 minutes"
    }
  }
}