Interviews

Cancel an invite

DELETE

/interviews/{id}

Cancels an interview with no recorded answers yet (status created, including expired invites). The candidate's link stops working, and the externalId becomes free, so you can POST a new invite with it. A cancelled interview no longer appears in the API (GET returns 404).

Once the candidate has recorded an answer (in_progress or later), the interview can't be cancelled (409).

Path parameters

idstringrequiredpattern ^[0-9a-fA-F]{24}$
A 24-character hex ID.

Example: "66f3a1c2e4b0a1d2c3e4f530"

Responses

200

The interview was cancelled.

Body object

dataCancelResultrequired
- idstringrequiredpattern ^[0-9a-fA-F]{24}$
  A 24-character hex ID.
- cancelledbooleanrequired
  Values: true
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": {
    "id": "66f4b7d9a1c2e3f4a5b6c701",
    "cancelled": true
  },
  "timestamp": 1790330400000
}

400

The request is invalid. message is the first validation error.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "limit must be between 1 and 100",
  "timestamp": 1790330400000
}

401

The API key is missing, malformed, invalid or revoked.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API key is required. Send it as 'Authorization: Bearer <key>'",
  "timestamp": 1790330400000
}

403

API access is disabled for your organization (any endpoint), or, when creating an invite, your organization has no active subscription or no interview credits left.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API access is not enabled for this organization",
  "timestamp": 1790330400000
}

404

The resource doesn't exist, was cancelled, or belongs to another organization. The API never returns 403 for another organization's IDs.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Interview not found",
  "timestamp": 1790330400000
}

409

The candidate has already recorded an answer, so the interview can't be cancelled.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Only interviews that have not been started can be cancelled",
  "timestamp": 1790330400000
}

429

Too many requests. Wait for Retry-After seconds (or the reset value in RateLimit), then retry.

Headers

RateLimitstring
Draft-7 rate limit state, e.g. limit=120, remaining=0, reset=42 (reset is in seconds).
RateLimit-Policystring
Draft-7 rate limit policy: the limit and the window in seconds.
Retry-Afterinteger
Seconds to wait before retrying.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Too many requests. Retry after the number of seconds in the RateLimit header.",
  "timestamp": 1790330400000
}