> ## 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.

# Update Interview

Updates an existing interview's details. Allows rescheduling, modifying assessment parameters, and updating candidate information before the interview starts.

<Warning>
  Most fields can only be updated for scheduled interviews. In-progress or completed interviews have limited update options.
</Warning>

## Path Parameters

<ParamField path="id" type="string" required>
  Unique interview identifier (e.g., `int_abc123def456`)
</ParamField>

## Request Body

<ParamField body="scheduled_at" type="string">
  ISO 8601 timestamp to reschedule the interview
</ParamField>

<ParamField body="position" type="string">
  Updated job position or role title
</ParamField>

<ParamField body="skills" type="array">
  Updated array of skills to assess
</ParamField>

<ParamField body="duration_minutes" type="integer">
  Updated interview duration in minutes (15-90)
</ParamField>

<ParamField body="difficulty" type="string">
  Updated difficulty level: `junior`, `intermediate`, `senior`, `expert`
</ParamField>

<ParamField body="company_name" type="string">
  Updated company name for personalization
</ParamField>

<ParamField body="instructions" type="string">
  Updated custom instructions for the AI interviewer
</ParamField>

<ParamField body="candidate_email" type="string">
  Updated candidate email (scheduled interviews only)
</ParamField>

<ParamField body="send_notification" type="boolean" default="true">
  Whether to notify candidate of changes via email
</ParamField>

<ParamField body="reschedule_reason" type="string">
  Reason for rescheduling (included in notification email)
</ParamField>

## Update Rules by Status

Different fields can be updated based on interview status:

| Field              | Scheduled | In Progress | Completed |
| ------------------ | --------- | ----------- | --------- |
| `scheduled_at`     | ✅ Yes     | ❌ No        | ❌ No      |
| `candidate_email`  | ✅ Yes     | ❌ No        | ❌ No      |
| `position`         | ✅ Yes     | ❌ No        | ❌ No      |
| `skills`           | ✅ Yes     | ❌ No        | ❌ No      |
| `duration_minutes` | ✅ Yes     | ❌ No        | ❌ No      |
| `difficulty`       | ✅ Yes     | ❌ No        | ❌ No      |
| `instructions`     | ✅ Yes     | ⚠️ Limited  | ❌ No      |
| `company_name`     | ✅ Yes     | ✅ Yes       | ❌ No      |

## Response

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

<ResponseField name="status" type="string">
  Current interview status
</ResponseField>

<ResponseField name="candidate_email" type="string">
  Updated candidate email
</ResponseField>

<ResponseField name="position" type="string">
  Updated job position
</ResponseField>

<ResponseField name="skills" type="array">
  Updated skills array
</ResponseField>

<ResponseField name="scheduled_at" type="string">
  Updated schedule timestamp
</ResponseField>

<ResponseField name="duration_minutes" type="integer">
  Updated duration
</ResponseField>

<ResponseField name="difficulty" type="string">
  Updated difficulty level
</ResponseField>

<ResponseField name="company_name" type="string">
  Updated company name
</ResponseField>

<ResponseField name="instructions" type="string">
  Updated custom instructions
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when interview was last updated
</ResponseField>

<ResponseField name="notification_sent" type="boolean">
  Whether update notification was sent to candidate
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL - Reschedule Interview theme={null}
  curl -X PATCH "https://backend.jobhive.ai/v1/interviews/int_abc123def456" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "scheduled_at": "2024-01-16T14:00:00Z",
      "reschedule_reason": "Candidate requested time change"
    }'
  ```

  ```bash cURL - Update Skills theme={null}
  curl -X PATCH "https://backend.jobhive.ai/v1/interviews/int_abc123def456" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "skills": ["JavaScript", "React", "Node.js", "TypeScript"],
      "difficulty": "senior",
      "instructions": "Focus on TypeScript advanced features and architectural patterns"
    }'
  ```

  ```javascript JavaScript theme={null}
  // Reschedule interview
  const updated = await jobhive.interviews.update('int_abc123def456', {
    scheduled_at: '2024-01-16T14:00:00Z',
    reschedule_reason: 'Interviewer unavailable',
    send_notification: true
  });

  console.log(`Interview rescheduled to: ${updated.scheduled_at}`);

  // Update assessment parameters
  const enhanced = await jobhive.interviews.update('int_def456ghi789', {
    skills: ['Python', 'Django', 'PostgreSQL', 'Redis'],
    difficulty: 'expert',
    duration_minutes: 60,
    instructions: 'Include system design questions about caching strategies'
  });
  ```

  ```python Python theme={null}
  # Bulk reschedule for weather emergency
  interviews_to_reschedule = client.interviews.list(
      scheduled_after='2024-01-15T08:00:00Z',
      scheduled_before='2024-01-15T18:00:00Z',
      status='scheduled'
  )

  for interview in interviews_to_reschedule.data:
      # Reschedule to next day, same time
      original_time = datetime.fromisoformat(interview.scheduled_at.replace('Z', '+00:00'))
      new_time = original_time + timedelta(days=1)
      
      client.interviews.update(
          interview.id,
          scheduled_at=new_time.isoformat(),
          reschedule_reason='Office closed due to weather emergency',
          send_notification=True
      )

  print(f"Rescheduled {len(interviews_to_reschedule.data)} interviews")
  ```
</RequestExample>

<ResponseExample>
  ```json Successful Update theme={null}
  {
    "success": true,
    "data": {
      "id": "int_abc123def456",
      "status": "scheduled",
      "candidate_email": "john.doe@example.com",
      "position": "Senior Full Stack Developer",
      "skills": ["JavaScript", "React", "Node.js", "TypeScript"],
      "scheduled_at": "2024-01-16T14:00:00Z",
      "duration_minutes": 60,
      "difficulty": "senior",
      "company_name": "TechCorp Inc",
      "instructions": "Focus on TypeScript advanced features and architectural patterns",
      "created_at": "2024-01-15T14:30:00Z",
      "updated_at": "2024-01-15T16:45:00Z",
      "notification_sent": true
    },
    "meta": {
      "timestamp": "2024-01-15T16:45:00Z",
      "request_id": "req_update_int_001"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json Interview Not Found theme={null}
  {
    "success": false,
    "error": {
      "code": "INTERVIEW_NOT_FOUND",
      "message": "Interview with ID 'int_invalid123' not found"
    }
  }
  ```

  ```json Cannot Update Completed Interview theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_OPERATION",
      "message": "Cannot update a completed interview",
      "details": {
        "current_status": "completed",
        "completed_at": "2024-01-15T16:30:00Z",
        "allowed_updates": []
      }
    }
  }
  ```

  ```json Validation Error theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid update parameters",
      "details": {
        "scheduled_at": "Cannot schedule interview in the past",
        "duration_minutes": "Must be between 15 and 90 minutes"
      }
    }
  }
  ```

  ```json Interview Already Started theme={null}
  {
    "success": false,
    "error": {
      "code": "INTERVIEW_IN_PROGRESS", 
      "message": "Cannot update core parameters while interview is active",
      "details": {
        "current_status": "in_progress",
        "started_at": "2024-01-15T15:32:00Z",
        "allowed_updates": ["company_name", "instructions"]
      }
    }
  }
  ```
</ResponseExample>

## Webhook Events

Updating an interview triggers webhook events based on the changes:

* `interview.updated` - Sent for any interview update
* `interview.rescheduled` - Sent when scheduled\_at is changed
* `candidate.notified` - Sent when notification email is delivered

## Best Practices

### Rescheduling Guidelines

<Tabs>
  <Tab title="Professional Communication">
    ```javascript theme={null}
    // Always provide a reason for rescheduling
    const rescheduled = await jobhive.interviews.update(interviewId, {
      scheduled_at: newDateTime,
      reschedule_reason: 'Interviewer has a scheduling conflict',
      send_notification: true
    });
    ```
  </Tab>

  <Tab title="Batch Operations">
    ```python theme={null}
    # Use batch updates for efficiency
    async def reschedule_batch(interview_ids, new_time, reason):
        updates = []
        for interview_id in interview_ids:
            try:
                result = await client.interviews.update(
                    interview_id,
                    scheduled_at=new_time,
                    reschedule_reason=reason
                )
                updates.append(result)
            except Exception as e:
                print(f"Failed to update {interview_id}: {e}")
        
        return updates
    ```
  </Tab>

  <Tab title="Validation">
    ```javascript theme={null}
    // Validate before updating
    function validateReschedule(newDateTime) {
      const now = new Date();
      const scheduledTime = new Date(newDateTime);
      
      if (scheduledTime <= now) {
        throw new Error('Cannot schedule interview in the past');
      }
      
      if (scheduledTime.getHours() < 9 || scheduledTime.getHours() > 17) {
        throw new Error('Interview must be scheduled during business hours');
      }
      
      return true;
    }
    ```
  </Tab>
</Tabs>

### Skill Assessment Updates

When updating skills or difficulty:

1. **Preserve Context**: Keep related skills together for coherent assessment
2. **Match Difficulty**: Ensure difficulty level matches the skills being tested
3. **Update Instructions**: Modify custom instructions to reflect new focus areas

<Note>
  Candidates receive email notifications for significant changes (rescheduling, skill updates) unless `send_notification: false` is specified.
</Note>

<Tip>
  Use the `reschedule_reason` field to maintain professional communication and reduce candidate confusion about changes.
</Tip>