Interviews

List interviews

GET

/interviews

Interviews in your organization (cancelled ones are left out).

Without updatedSince, results are sorted newest first (by createdAt).
With updatedSince, results are sorted by updatedAt ascending, then by id. The filter is inclusive (updatedAt >= updatedSince), so when you poll you'll see the last record again. Deduplicate by (id, updatedAt).

An invite passing its inviteExpiresAt does not change updatedAt. To find expired invites, compare inviteExpiresAt with the current time yourself, or use status=expired.

Query parameters

pageintegermin 1
Page number, starting at 1.

Default: 1
limitintegermin 1max 100
Items per page.

Default: 20
positionIdstringpattern ^[0-9a-fA-F]{24}$
Only return interviews for this position.

Example: "66f3a1c2e4b0a1d2c3e4f530"
statusstring
Only return interviews with this status. expired includes created invites whose inviteExpiresAt has passed; created leaves them out.

Values: "created", "in_progress", "completed", "abandoned", "expired"
externalIdstringmax length 200
Only return interviews with this externalId (exact match).

Example: "APP-2026-00042"
updatedSincestring (date-time)
Only return interviews with updatedAt at or after this ISO 8601 date-time (inclusive).

Example: "2026-09-24T10:00:00.000Z"

Responses

200

A page of interviews.

Body object

dataInterview[]required
- idstringrequiredpattern ^[0-9a-fA-F]{24}$
  A 24-character hex ID.
- positionIdstringrequiredpattern ^[0-9a-fA-F]{24}$
  A 24-character hex ID.
- externalIdstring | nullrequired
  Your ID for this candidate or application, as sent on the invite.
- sourcestringrequired
  api for invites created through this API; dashboard for candidates who applied through a position link.
  
  Values: "dashboard", "api"
- statusstringrequired
  - created: invited; no answer recorded yet (the candidate may have opened the link).
  - in_progress: at least one answer recorded.
  - completed: all questions answered.
  - abandoned: the candidate left without finishing.
  - expired: the interview expired, or the invite passed inviteExpiresAt while still created.
  Values: "created", "in_progress", "completed", "abandoned", "expired"
- approvalStatusstringrequired
  The reviewer's decision in the Videcoot dashboard.
  
  Values: "pending", "approved", "rejected"
- candidateCandidaterequired
- inviteUrlstring (uri) | nullrequired
  The candidate's personal interview link. null for interviews not created by the API.
- inviteExpiresAtstring (date-time) | nullrequired
  After this time an invite still in created (no answers recorded) reports status expired. null for interviews not created by the API.
- answeredQuestionsintegerrequiredmin 0
- completedAtstring (date-time) | nullrequired
- analysisStatusstringrequired
  Values: "not_requested", "pending", "processing", "completed", "failed"
- createdAtstring (date-time) | nullrequired
- updatedAtstring (date-time) | nullrequired
metaPaginationMetarequired
- totalintegerrequired
  Total number of matching items.
- pageintegerrequiredmin 1
- limitintegerrequiredmin 1max 100
- totalPagesintegerrequired
  ceil(total / limit). It is 0 when there are no results.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": [
    {
      "id": "66f4b7d9a1c2e3f4a5b6c701",
      "positionId": "66f3a1c2e4b0a1d2c3e4f530",
      "externalId": "APP-2026-00042",
      "source": "api",
      "status": "completed",
      "approvalStatus": "pending",
      "candidate": {
        "firstName": "Nok",
        "lastName": "Srisuk",
        "email": "nok.srisuk@example.com",
        "phoneNumber": "812345678",
        "countryCode": "+66"
      },
      "inviteUrl": "https://app.videcoot.com/interviews/positions/66f3a1c2e4b0a1d2c3e4f530?invite=a5880531dab9825f995ac073d405b57d240199fd0487609962899c34e031d4e5",
      "inviteExpiresAt": "2026-10-09T10:00:00.000Z",
      "answeredQuestions": 2,
      "completedAt": "2026-09-26T02:31:05.000Z",
      "analysisStatus": "not_requested",
      "createdAt": "2026-09-25T10:00:00.000Z",
      "updatedAt": "2026-09-26T02:31:05.000Z"
    },
    {
      "id": "66f4b7d9a1c2e3f4a5b6c702",
      "positionId": "66f3a1c2e4b0a1d2c3e4f530",
      "externalId": null,
      "source": "dashboard",
      "status": "in_progress",
      "approvalStatus": "pending",
      "candidate": {
        "firstName": "Malee",
        "lastName": "Wong",
        "email": "malee.wong@example.com",
        "phoneNumber": null,
        "countryCode": null
      },
      "inviteUrl": null,
      "inviteExpiresAt": null,
      "answeredQuestions": 1,
      "completedAt": null,
      "analysisStatus": "not_requested",
      "createdAt": "2026-09-26T04:02:10.000Z",
      "updatedAt": "2026-09-26T04:05:44.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  },
  "timestamp": 1790395200000
}

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
}

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
}