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

# Cancel Interview

Cancels a scheduled interview or terminates an in-progress interview. This action is irreversible and will immediately notify the candidate if the interview hasn't started yet.

<Warning>
  Canceling an interview is permanent. Consider using the update endpoint to reschedule instead.
</Warning>

## Path Parameters

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

## Query Parameters

<ParamField query="reason" type="string">
  Reason for cancellation to include in candidate notification
</ParamField>

<ParamField query="send_notification" type="boolean" default="true">
  Whether to send cancellation notification to candidate
</ParamField>

<ParamField query="refund_credits" type="boolean" default="true">
  Whether to refund credits for unused interview (scheduled interviews only)
</ParamField>

## Response

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

<ResponseField name="status" type="string">
  Updated interview status: `cancelled`
</ResponseField>

<ResponseField name="cancelled_at" type="string">
  ISO 8601 timestamp when interview was cancelled
</ResponseField>

<ResponseField name="cancellation_reason" type="string">
  Reason provided for cancellation
</ResponseField>

<ResponseField name="refund_details" type="object">
  Credit refund information (if applicable)

  <Expandable title="Refund details">
    <ResponseField name="credits_refunded" type="integer">
      Number of credits returned to account
    </ResponseField>

    <ResponseField name="refund_reason" type="string">
      Reason for refund eligibility
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Cancellation Rules

Different rules apply based on interview status:

| Status        | Cancellation Allowed | Credit Refund    | Candidate Notification |
| ------------- | -------------------- | ---------------- | ---------------------- |
| `scheduled`   | ✅ Yes                | ✅ Full refund    | ✅ Auto-sent            |
| `in_progress` | ✅ Yes                | ❌ No refund      | ❌ Not applicable       |
| `completed`   | ❌ Not allowed        | ❌ Not applicable | ❌ Not applicable       |
| `cancelled`   | ❌ Already cancelled  | ❌ Not applicable | ❌ Not applicable       |

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://backend.jobhive.ai/v1/interviews/int_abc123def456" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL with Reason theme={null}
  curl -X DELETE "https://backend.jobhive.ai/v1/interviews/int_abc123def456?reason=Candidate%20withdrew%20application" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const result = await jobhive.interviews.delete('int_abc123def456', {
    reason: 'Position has been filled',
    send_notification: true
  });

  console.log(`Interview cancelled: ${result.id}`);
  ```

  ```python Python theme={null}
  result = client.interviews.delete(
      'int_abc123def456',
      reason='Position has been filled',
      send_notification=True
  )

  print(f"Interview cancelled: {result.id}")
  print(f"Credits refunded: {result.refund_details.credits_refunded}")
  ```
</RequestExample>

<ResponseExample>
  ```json Scheduled Interview Cancelled theme={null}
  {
    "success": true,
    "data": {
      "id": "int_abc123def456",
      "status": "cancelled",
      "cancelled_at": "2024-01-15T14:45:00Z",
      "cancellation_reason": "Position has been filled",
      "refund_details": {
        "credits_refunded": 1,
        "refund_reason": "Interview cancelled before start time"
      },
      "notification_sent": true
    },
    "meta": {
      "timestamp": "2024-01-15T14:45:00Z",
      "request_id": "req_cancel_int_001"
    }
  }
  ```

  ```json In-Progress Interview Terminated theme={null}
  {
    "success": true,
    "data": {
      "id": "int_def456ghi789",
      "status": "cancelled",
      "cancelled_at": "2024-01-15T15:23:00Z",
      "cancellation_reason": "Technical difficulties",
      "refund_details": null,
      "notification_sent": false
    },
    "meta": {
      "timestamp": "2024-01-15T15:23:00Z",
      "request_id": "req_cancel_int_002"
    }
  }
  ```
</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 Cancel Completed Interview theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_OPERATION",
      "message": "Cannot cancel a completed interview",
      "details": {
        "current_status": "completed",
        "completed_at": "2024-01-15T16:30:00Z"
      }
    }
  }
  ```

  ```json Already Cancelled theme={null}
  {
    "success": false,
    "error": {
      "code": "INTERVIEW_ALREADY_CANCELLED",
      "message": "Interview is already cancelled",
      "details": {
        "cancelled_at": "2024-01-15T14:00:00Z",
        "cancellation_reason": "Candidate withdrew"
      }
    }
  }
  ```
</ResponseExample>

## Webhook Events

Cancelling an interview triggers the following webhook events:

* `interview.cancelled` - Sent when interview is successfully cancelled
* `candidate.notified` - Sent when cancellation notification is delivered (if applicable)
* `credits.refunded` - Sent when credits are refunded to account (if applicable)

<Note>
  Candidates will receive an email notification about the cancellation unless `send_notification=false` is specified. The notification includes the cancellation reason if provided.
</Note>

<Tip>
  Consider using the [Update Interview](/api-reference/endpoint/update) endpoint to reschedule instead of cancelling, which preserves the interview history and avoids notification churn.
</Tip>