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.

Canceling an interview is permanent. Consider using the update endpoint to reschedule instead.

Path Parameters

string

required

Unique interview identifier (e.g., int_abc123def456)

Query Parameters

string

Reason for cancellation to include in candidate notification

boolean

default:"true"

Whether to send cancellation notification to candidate

boolean

default:"true"

Whether to refund credits for unused interview (scheduled interviews only)

Response

string

Unique interview identifier

string

Updated interview status: cancelled

string

ISO 8601 timestamp when interview was cancelled

string

Reason provided for cancellation

object

Credit refund information (if applicable)

Show Refund details

integer

Number of credits returned to account

string

Reason for refund eligibility

boolean

Whether cancellation notification was sent to candidate

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

curl -X DELETE "https://backend.jobhive.ai/v1/interviews/int_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X DELETE "https://backend.jobhive.ai/v1/interviews/int_abc123def456?reason=Candidate%20withdrew%20application" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

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}")

{
  "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"
  }
}

{
  "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"
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "INTERVIEW_NOT_FOUND",
    "message": "Interview with ID 'int_invalid123' not found"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_OPERATION",
    "message": "Cannot cancel a completed interview",
    "details": {
      "current_status": "completed",
      "completed_at": "2024-01-15T16:30:00Z"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INTERVIEW_ALREADY_CANCELLED",
    "message": "Interview is already cancelled",
    "details": {
      "cancelled_at": "2024-01-15T14:00:00Z",
      "cancellation_reason": "Candidate withdrew"
    }
  }
}

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)

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

Consider using the Update Interview endpoint to reschedule instead of cancelling, which preserves the interview history and avoids notification churn.

Getting Started

Core Resources

Advanced Features

Path Parameters

Query Parameters

Response

Cancellation Rules

Examples

Error Responses

Webhook Events

​Path Parameters

​Query Parameters

​Response

​Cancellation Rules

​Examples

​Error Responses

​Webhook Events

Path Parameters

Query Parameters

Response

Cancellation Rules

Examples

Error Responses

Webhook Events