Video interviews

Create job-based or resume-based video interviews for candidates in your organization. Each API-created interview consumes 10 Talynce credits (₹7 per credit). Purchase credits at /dashboard/credits.

Requires a paid plan (REST API access). Free-plan organizations receive 403 upgrade_required.

List and detail existing interviews via GET /api/v1/screenings with type=video.

For resume-based interviews, omit interview_questions to auto-generate five spoken questions from the candidate's resume, or pass your own list (1–10 spoken questions).

Create request body

POST /api/v1/video-interviews
Field	Type	Required	Description
candidate_id	string (uuid)	Yes	Org candidate id
question_source	"job" \| "resume"	Yes	Job/JD questions or resume-based questions
job_id	string (uuid)	When question_source=job	Job id (required for job-based)
send_invite_email	boolean	—	Send invitation email (default true)
interview_questions	object[]	—	Optional custom questions (1–10). When omitted, questions are auto-generated from the job JD or candidate resume. Resume-based interviews must use spoken questions only.

Examples

Job-based interview

POST body — job-based

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "job",
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "send_invite_email": true
}

Resume-based interview

POST body — resume-based (auto-generate questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true
}

Resume-based with custom questions

POST body — resume-based (custom questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true,
  "interview_questions": [
    { "text": "Walk us through your most recent role and key responsibilities.", "kind": "spoken" },
    { "text": "Describe a project from your resume where you led delivery end-to-end.", "kind": "spoken" },
    { "text": "Which skills on your resume do you use most often? Give a concrete example.", "kind": "spoken" },
    { "text": "Tell us about a difficult technical problem you solved.", "kind": "spoken" },
    { "text": "What are you looking for in your next opportunity?", "kind": "spoken" }
  ]
}

Response (201)

data object
Field	Type	Required	Description
id	string (uuid)	—	Interview id
session_token	string	—	Candidate session token
invite_url	string	—	Full URL for candidate
question_source	"job" \| "resume"	—	Question source
initiated_via	"api"	—	Always api for this endpoint
status	"invited"	—	Initial status

Response example

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "session_token": "vi_abc123...",
    "invite_url": "https://talynce.com/interview/vi_abc123...",
    "question_source": "resume",
    "initiated_via": "api",
    "status": "invited"
  }
}

Errors

403 insufficient_credits — balance below 10 credits
403 upgrade_required — free plan
400 validation_error — missing job_id for job source, or candidate has no resume
404 not_found — candidate or job not in your organization

POST/api/v1/video-interviews

Create a video interview (10 credits). Returns invite URL.

Video interviews

Requires a paid plan (REST API access). Free-plan organizations receive 403 upgrade_required.

List and detail existing interviews via GET /api/v1/screenings with type=video.

For resume-based interviews, omit interview_questions to auto-generate five spoken questions from the candidate's resume, or pass your own list (1–10 spoken questions).

Create request body

POST /api/v1/video-interviews
Field	Type	Required	Description
candidate_id	string (uuid)	Yes	Org candidate id
question_source	"job" \| "resume"	Yes	Job/JD questions or resume-based questions
job_id	string (uuid)	When question_source=job	Job id (required for job-based)
send_invite_email	boolean	—	Send invitation email (default true)
interview_questions	object[]	—	Optional custom questions (1–10). When omitted, questions are auto-generated from the job JD or candidate resume. Resume-based interviews must use spoken questions only.

Examples

Job-based interview

POST body — job-based

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "job",
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "send_invite_email": true
}

Resume-based interview

POST body — resume-based (auto-generate questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true
}

Resume-based with custom questions

POST body — resume-based (custom questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true,
  "interview_questions": [
    { "text": "Walk us through your most recent role and key responsibilities.", "kind": "spoken" },
    { "text": "Describe a project from your resume where you led delivery end-to-end.", "kind": "spoken" },
    { "text": "Which skills on your resume do you use most often? Give a concrete example.", "kind": "spoken" },
    { "text": "Tell us about a difficult technical problem you solved.", "kind": "spoken" },
    { "text": "What are you looking for in your next opportunity?", "kind": "spoken" }
  ]
}

Response (201)

data object
Field	Type	Required	Description
id	string (uuid)	—	Interview id
session_token	string	—	Candidate session token
invite_url	string	—	Full URL for candidate
question_source	"job" \| "resume"	—	Question source
initiated_via	"api"	—	Always api for this endpoint
status	"invited"	—	Initial status

Response example

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "session_token": "vi_abc123...",
    "invite_url": "https://talynce.com/interview/vi_abc123...",
    "question_source": "resume",
    "initiated_via": "api",
    "status": "invited"
  }
}

Errors

403 insufficient_credits — balance below 10 credits
403 upgrade_required — free plan
400 validation_error — missing job_id for job source, or candidate has no resume
404 not_found — candidate or job not in your organization

POST/api/v1/video-interviews

Create a video interview (10 credits). Returns invite URL.

Video interviews

Requires a paid plan (REST API access). Free-plan organizations receive 403 upgrade_required.

List and detail existing interviews via GET /api/v1/screenings with type=video.

For resume-based interviews, omit interview_questions to auto-generate five spoken questions from the candidate's resume, or pass your own list (1–10 spoken questions).

Create request body

POST /api/v1/video-interviews
Field	Type	Required	Description
candidate_id	string (uuid)	Yes	Org candidate id
question_source	"job" \| "resume"	Yes	Job/JD questions or resume-based questions
job_id	string (uuid)	When question_source=job	Job id (required for job-based)
send_invite_email	boolean	—	Send invitation email (default true)
interview_questions	object[]	—	Optional custom questions (1–10). When omitted, questions are auto-generated from the job JD or candidate resume. Resume-based interviews must use spoken questions only.

Examples

Job-based interview

POST body — job-based

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "job",
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "send_invite_email": true
}

Resume-based interview

POST body — resume-based (auto-generate questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true
}

Resume-based with custom questions

POST body — resume-based (custom questions)

{
  "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
  "question_source": "resume",
  "send_invite_email": true,
  "interview_questions": [
    { "text": "Walk us through your most recent role and key responsibilities.", "kind": "spoken" },
    { "text": "Describe a project from your resume where you led delivery end-to-end.", "kind": "spoken" },
    { "text": "Which skills on your resume do you use most often? Give a concrete example.", "kind": "spoken" },
    { "text": "Tell us about a difficult technical problem you solved.", "kind": "spoken" },
    { "text": "What are you looking for in your next opportunity?", "kind": "spoken" }
  ]
}

Response (201)

data object
Field	Type	Required	Description
id	string (uuid)	—	Interview id
session_token	string	—	Candidate session token
invite_url	string	—	Full URL for candidate
question_source	"job" \| "resume"	—	Question source
initiated_via	"api"	—	Always api for this endpoint
status	"invited"	—	Initial status

Response example

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "session_token": "vi_abc123...",
    "invite_url": "https://talynce.com/interview/vi_abc123...",
    "question_source": "resume",
    "initiated_via": "api",
    "status": "invited"
  }
}

Errors

403 insufficient_credits — balance below 10 credits
403 upgrade_required — free plan
400 validation_error — missing job_id for job source, or candidate has no resume
404 not_found — candidate or job not in your organization

POST/api/v1/video-interviews

Create a video interview (10 credits). Returns invite URL.