VidecootAPI

End-to-end walkthrough

Create a position, invite a candidate, poll progress and read the AI analysis.

These examples use curl and the SIT host.

export VIDECOOT_API_KEY="vdc_live_..."
export BASE="https://sit-api.videcoot.com/api/integration/v1"

List companies

Positions belong to a company. Companies and teams are managed in the Videcoot dashboard; the API can only read them.

curl "$BASE/companies?limit=100" -H "Authorization: Bearer $VIDECOOT_API_KEY"
{
  "data": [
    {
      "id": "66f3a1c2e4b0a1d2c3e4f510",
      "name": "Acme Logistics",
      "website": "https://acme-logistics.example.com"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 100, "totalPages": 1 },
  "timestamp": 1790330400000
}

GET /teams works the same way and returns { id, name }.

Create a position

curl -X POST "$BASE/positions" \
  -H "Authorization: Bearer $VIDECOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Supervisor",
    "companyId": "66f3a1c2e4b0a1d2c3e4f510",
    "interviewCondition": "Please record in a quiet room.",
    "questions": [
      { "text": "Tell us about a time you led a team through a busy period.", "timeLimit": 3, "order": 1 },
      { "text": "How do you keep a warehouse safe?", "timeLimit": 2, "order": 2 }
    ],
    "analyzePrompt": "Focus on leadership and safety awareness."
  }'

Returns 201 with the position. Save data.id; it's the POSITION_ID below.

{
  "data": {
    "id": "66f3a1c2e4b0a1d2c3e4f530",
    "name": "Warehouse Supervisor",
    "status": "open",
    "companyId": "66f3a1c2e4b0a1d2c3e4f510",
    "teamId": null,
    "interviewCondition": "Please record in a quiet room.",
    "questions": [
      {
        "id": "66f3a1c2e4b0a1d2c3e4f531",
        "text": "Tell us about a time you led a team through a busy period.",
        "timeLimit": 3,
        "order": 1
      },
      {
        "id": "66f3a1c2e4b0a1d2c3e4f532",
        "text": "How do you keep a warehouse safe?",
        "timeLimit": 2,
        "order": 2
      }
    ],
    "createdAt": "2026-09-25T10:00:00.000Z",
    "updatedAt": "2026-09-25T10:00:00.000Z"
  },
  "timestamp": 1790330400000
}

Rules:

  • name 2–100 characters. companyId (and teamId, if sent) must belong to your organization.
  • 1–15 questions. Each has text (up to 1000 characters), timeLimit in minutes (1–5) and a unique order (0 or more).
  • status defaults to open (open, closed or draft). Only open positions accept invites.
  • interviewCondition (up to 500 characters) is shown to the candidate before they start.
  • analyzePrompt (up to 10,000 characters) guides the AI analysis. It's never returned.

To change a position, PATCH /positions/{id} with only the fields you want to change. Sending questions replaces the whole list. Include a question's id to keep it, including any image added in the dashboard. "teamId": null removes the team.

Invite a candidate

export POSITION_ID="66f3a1c2e4b0a1d2c3e4f530"

curl -X POST "$BASE/positions/$POSITION_ID/invites" \
  -H "Authorization: Bearer $VIDECOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": {
      "firstName": "Nok",
      "lastName": "Srisuk",
      "email": "nok.srisuk@example.com",
      "phoneNumber": "812345678",
      "countryCode": "+66"
    },
    "externalId": "APP-2026-00042",
    "sendEmail": true,
    "expiresInDays": 14
  }'

Returns 201 for a new invite:

{
  "data": {
    "id": "66f4b7d9a1c2e3f4a5b6c701",
    "positionId": "66f3a1c2e4b0a1d2c3e4f530",
    "externalId": "APP-2026-00042",
    "source": "api",
    "status": "created",
    "approvalStatus": "pending",
    "candidate": {
      "firstName": "Nok",
      "lastName": "Srisuk",
      "email": "nok.srisuk@example.com",
      "phoneNumber": "812345678",
      "countryCode": "+66"
    },
    "inviteUrl": "https://sit-app.videcoot.com/interviews/positions/66f3a1c2e4b0a1d2c3e4f530?invite=a5880531dab9825f995ac073d405b57d240199fd0487609962899c34e031d4e5",
    "inviteExpiresAt": "2026-10-09T10:00:00.000Z",
    "answeredQuestions": 0,
    "completedAt": null,
    "analysisStatus": "not_requested",
    "createdAt": "2026-09-25T10:00:00.000Z",
    "updatedAt": "2026-09-25T10:00:00.000Z",
    "emailSent": true
  },
  "timestamp": 1790330400000
}

Save data.id against your externalId. That's the INTERVIEW_ID below.

Who sends the invite?

  • "sendEmail": true (the default): Videcoot emails the candidate their link. If the email can't be sent, the invite is still created and emailSent is false. You can then send inviteUrl yourself.
  • "sendEmail": false: Videcoot sends nothing. Send inviteUrl to the candidate yourself, by email, SMS or in your careers portal. The link is personal to this candidate; its email field is locked.

Other fields:

  • candidate.firstName and candidate.lastName: required, up to 100 characters each.
  • candidate.email: required. It's stored in lowercase.
  • candidate.phoneNumber (6–15 digits) and candidate.countryCode (like +66): optional.
  • externalId: optional but strongly recommended, up to 200 characters. See Idempotency.
  • expiresInDays: 1–90, default 14. After this, an invite with no recorded answers reports status: "expired" and the link stops working.

Credits. Creating an invite doesn't use a credit; it only checks that your organization has credits left (otherwise 403). One credit is used when the candidate starts the interview.

One live interview per candidate and position. If the same email already has a live invite from the API for this position, you get that invite back with 200. If the candidate is already doing an interview they started themselves, or a live API invite with a different externalId, you get 409. A candidate can have at most 3 interviews per position.

Poll for progress

For one interview:

export INTERVIEW_ID="66f4b7d9a1c2e3f4a5b6c701"

curl "$BASE/interviews/$INTERVIEW_ID" -H "Authorization: Bearer $VIDECOOT_API_KEY"

The detail response is the interview summary plus answers and analysis:

{
  "data": {
    "id": "66f4b7d9a1c2e3f4a5b6c701",
    "status": "completed",
    "answeredQuestions": 2,
    "completedAt": "2026-09-26T02:31:05.000Z",
    "analysisStatus": "not_requested",
    "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"
      }
    ],
    "analysis": { "status": "not_requested", "requestedAt": null, "completedAt": null }
  },
  "timestamp": 1790395200000
}

(Fields shortened. The full summary is the same as in the invite response, without emailSent.)

To sync many interviews, poll the list with updatedSince instead. See the polling recipe.

curl "$BASE/interviews?updatedSince=2026-09-25T00:00:00.000Z&limit=100&page=1" \
  -H "Authorization: Bearer $VIDECOOT_API_KEY"

Other filters: positionId, status and externalId (exact match).

Request analysis

Once status is completed:

curl -X POST "$BASE/interviews/$INTERVIEW_ID/analysis" \
  -H "Authorization: Bearer $VIDECOOT_API_KEY"
  • 202: analysis was queued ("status": "pending").
  • 200: analysis was already requested. You get the current state, and nothing new is queued. Safe to call again.
  • 409: the interview isn't completed yet.
{
  "data": {
    "status": "pending",
    "requestedAt": "2026-09-26T03:00:00.000Z",
    "completedAt": null,
    "result": null
  },
  "timestamp": 1790398800000
}

Poll the analysis

Analysis usually takes a few minutes. Poll every 30–60 seconds until status is completed or failed.

curl "$BASE/interviews/$INTERVIEW_ID/analysis" -H "Authorization: Bearer $VIDECOOT_API_KEY"
{
  "data": {
    "status": "completed",
    "requestedAt": "2026-09-26T03:00:00.000Z",
    "completedAt": "2026-09-26T03:01:42.000Z",
    "result": {
      "evaluationScores": {
        "communication_score": 84,
        "criteria_match_score": 78,
        "competency_score": 81,
        "cultural_fit_score": 88,
        "overall_score": 82
      },
      "detailedAssessment": {
        "communication": {
          "strengths": ["Clear structure"],
          "weaknesses": ["Some answers ran long"],
          "observations": "Explains decisions step by step."
        },
        "competency_assessment": {
          "observed_strengths": ["Shift planning"],
          "areas_for_improvement": ["Inventory software"],
          "relevant_examples": ["Reorganised picking routes during peak season"],
          "observations": "Strong hands-on leadership."
        },
        "red_flags": [],
        "positive_indicators": ["Took ownership of a safety incident"]
      },
      "hiringRecommendation": {
        "decision": "YES",
        "confidence_level": "MEDIUM",
        "primary_reasons": ["Relevant supervisory experience"],
        "risks": ["Limited WMS experience"],
        "conditions": ["Training on the warehouse management system"]
      },
      "summary": {
        "one_line_summary": "Experienced, safety-minded supervisor who communicates clearly.",
        "key_strengths": "Team leadership under pressure.",
        "key_concerns": "Little exposure to warehouse software.",
        "fit_assessment": "GOOD"
      },
      "analyzedAt": "2026-09-26T03:01:42.000Z"
    }
  },
  "timestamp": 1790398920000
}
  • hiringRecommendation.decision: STRONG_YES, YES, MAYBE or NO.
  • hiringRecommendation.confidence_level: HIGH, MEDIUM or LOW.
  • summary.fit_assessment: EXCELLENT, GOOD, FAIR or POOR.

If status is failed, POST the analysis again to retry.