Create Interview

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

string

required

Email address of the candidate to be interviewed

string

required

Job position or role title for the interview

array

required

Array of skills to assess during the interview

Show Example skills

Programming languages: “JavaScript”, “Python”, “Java”
Frameworks: “React”, “Django”, “Spring Boot”
Concepts: “Data Structures”, “System Design”, “Machine Learning”

integer

default:"30"

Interview duration in minutes (15-90 minutes)

string

default:"intermediate"

Interview difficulty level

Show Difficulty levels

junior: Entry-level questions
intermediate: Mid-level complexity
senior: Advanced technical depth
expert: Architect-level challenges

string

Company name to personalize the interview experience

string

Custom instructions or focus areas for the AI interviewer

boolean

default:"true"

Whether to automatically send interview invitation to candidate

string

ISO 8601 timestamp to schedule interview for future date/time

boolean

default:"false"

Enable test mode to avoid consuming production credits

Response

string

Unique interview identifier

string

Current interview status: scheduled, in_progress, completed, cancelled

string

Email address of the candidate

string

Job position for the interview

string

Direct URL for candidate to join the interview

string

ISO 8601 timestamp when interview is scheduled

integer

Estimated interview duration in minutes

array

Array of skills to be assessed

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": "john.doe@example.com",
    "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"
  }'

const interview = await jobhive.interviews.create({
  candidate_email: "john.doe@example.com",
  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"
});

console.log(`Interview created: ${interview.id}`);

interview = client.interviews.create(
    candidate_email="john.doe@example.com",
    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"
)

print(f"Interview created: {interview.id}")

{
  "success": true,
  "data": {
    "id": "int_abc123def456",
    "status": "scheduled",
    "candidate_email": "john.doe@example.com",
    "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"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retry_after": 60
    }
  }
}

Getting Started

Core Resources

Advanced Features

Request Body

Response

Examples

Error Responses

​Request Body

​Response

​Examples

​Error Responses

Request Body

Response

Examples

Error Responses