Interviews

Get an interview

GET

/interviews/{id}

The interview summary plus its answers (with video links) and the analysis status.

Path parameters

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

Example: "66f3a1c2e4b0a1d2c3e4f530"

Responses

200

The interview.

Body object

dataInterviewDetailrequired
- 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
- answersAnswer[]required
  In the order they were recorded.
- analysisobjectrequired
  The analysis status. Get the full result from GET /interviews/{id}/analysis.
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": "processing",
    "createdAt": "2026-09-25T10:00:00.000Z",
    "updatedAt": "2026-09-26T03:00:02.000Z",
    "answers": [
      {
        "questionId": "66f3a1c2e4b0a1d2c3e4f531",
        "questionText": "Tell us about a time you led a team through a busy period.",
        "videoUrl": "https://videcoot.sgp1.digitaloceanspaces.com/interviews/66f4b7d9a1c2e3f4a5b6c701/answer-1.webm",
        "answeredAt": "2026-09-26T02:14:51.000Z"
      },
      {
        "questionId": "66f3a1c2e4b0a1d2c3e4f532",
        "questionText": "How do you keep a warehouse safe?",
        "videoUrl": "https://videcoot.sgp1.digitaloceanspaces.com/interviews/66f4b7d9a1c2e3f4a5b6c701/answer-2.webm",
        "answeredAt": "2026-09-26T02:31:05.000Z"
      }
    ],
    "analysis": {
      "status": "processing",
      "requestedAt": "2026-09-26T03:00:00.000Z",
      "completedAt": null
    }
  },
  "timestamp": 1790398800000
}

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
}

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
}