Polling and statuses · Videcoot API

The API doesn't send webhooks in v1. Poll the interview list with updatedSince:

cursor = last saved cursor or now - 1 day
every 5 minutes:
  page = 1
  loop:
    GET /interviews?updatedSince={cursor}&limit=100&page={page}
    for each interview: upsert by id; skip if (id, updatedAt) already processed
    if page >= meta.totalPages: break
    page += 1
  cursor = max(updatedAt seen)   # updatedSince is inclusive (>=), so duplicates are expected

With updatedSince, results are sorted by updatedAt ascending, then by id.
Save the cursor only after a pass succeeds, so a crash replays instead of skipping.
An empty result has meta.totalPages of 0, which also ends the loop.

Note: an invite passing inviteExpiresAt doesn't change updatedAt, so it won't show up in updatedSince polls. Compare inviteExpiresAt with the current time yourself, or query GET /interviews?status=expired.

Statuses

Interview status

created ──▶ in_progress ──▶ completed
   │             │
   ▼             ▼
expired      abandoned

Status	Meaning
`created`	Invited; no answer recorded yet. The candidate may have opened the link.
`in_progress`	At least one answer recorded. `answeredQuestions` shows how many.
`completed`	All questions answered. `completedAt` is set.
`expired`	The invite passed `inviteExpiresAt` while still `created`, or the interview expired.
`abandoned`	The candidate left without finishing.

source is api for invites created through this API and dashboard for candidates who applied through a position link.

approvalStatus (pending, approved or rejected) is the reviewer's decision in the Videcoot dashboard.

Analysis status (analysisStatus on the interview, status on /analysis)

not_requested ──▶ pending ──▶ processing ──▶ completed
                                        └──▶ failed

Status	Meaning
`not_requested`	Nobody has requested analysis yet.
`pending`	Queued.
`processing`	Running.
`completed`	Done. `result` is available from `GET /interviews/{id}/analysis`.
`failed`	It didn't work. `POST` again to retry.

When to request analysis: only once the interview's status is completed. Earlier requests return 409. Analysis is also available in the Videcoot dashboard; a request from either place counts, and the API won't queue it twice.