> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jobhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="candidate_email" type="string" required>
  Email address of the candidate to be interviewed
</ParamField>

<ParamField body="position" type="string" required>
  Job position or role title for the interview
</ParamField>

<ParamField body="skills" type="array" required>
  Array of skills to assess during the interview

  <Expandable title="Example skills">
    * Programming languages: "JavaScript", "Python", "Java"
    * Frameworks: "React", "Django", "Spring Boot"
    * Concepts: "Data Structures", "System Design", "Machine Learning"
  </Expandable>
</ParamField>

<ParamField body="duration_minutes" type="integer" default="30">
  Interview duration in minutes (15-90 minutes)
</ParamField>

<ParamField body="difficulty" type="string" default="intermediate">
  Interview difficulty level

  <Expandable title="Difficulty levels">
    * `junior`: Entry-level questions
    * `intermediate`: Mid-level complexity
    * `senior`: Advanced technical depth
    * `expert`: Architect-level challenges
  </Expandable>
</ParamField>

<ParamField body="company_name" type="string">
  Company name to personalize the interview experience
</ParamField>

<ParamField body="instructions" type="string">
  Custom instructions or focus areas for the AI interviewer
</ParamField>

<ParamField body="send_invitation" type="boolean" default="true">
  Whether to automatically send interview invitation to candidate
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 timestamp to schedule interview for future date/time
</ParamField>

<ParamField body="test_mode" type="boolean" default="false">
  Enable test mode to avoid consuming production credits
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique interview identifier
</ResponseField>

<ResponseField name="status" type="string">
  Current interview status: `scheduled`, `in_progress`, `completed`, `cancelled`
</ResponseField>

<ResponseField name="candidate_email" type="string">
  Email address of the candidate
</ResponseField>

<ResponseField name="position" type="string">
  Job position for the interview
</ResponseField>

<ResponseField name="interview_url" type="string">
  Direct URL for candidate to join the interview
</ResponseField>

<ResponseField name="scheduled_at" type="string">
  ISO 8601 timestamp when interview is scheduled
</ResponseField>

<ResponseField name="estimated_duration" type="integer">
  Estimated interview duration in minutes
</ResponseField>

<ResponseField name="skills" type="array">
  Array of skills to be assessed
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when interview was created
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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}")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json Validation Error theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json Rate Limit Error   theme={null}
  {
    "success": false,
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Too many requests. Please try again later.",
      "details": {
        "retry_after": 60
      }
    }
  }
  ```
</ResponseExample>