Skip to main content
POST
Create role

Authorizations

x-api-key
string
header
required

API key with the iv_live_ prefix. Create one under Developer → API Keys.

Body

application/json
template_name
string
required

Display name, e.g. "Senior Backend Engineer"

use_case
enum<string>
required

Determines recommendation vocabulary

Available options:
hiring,
admissions,
training,
custom_api
description
string
required

Raw job-description text. The AI-formatted JD is returned separately as knowledge_base_extracted.

success_outcome
enum<string>

Outcome label (auto-derived from use_case if omitted)

Available options:
hire_no_hire,
admit_reject,
pass_fail,
ready_needs_training,
certified_not_certified,
custom
status
enum<string>

Default: active

Available options:
draft,
active,
archived
domain
string

Industry or field, e.g. "Software Engineering"

level
string

Seniority, e.g. "Senior / 5+ years"

experience_or_current_level
string

Free-text experience or current level

skills
string[]

Technical skills to probe, e.g. ["Go", "PostgreSQL"]

soft_skills
string[]

Behavioural traits, e.g. ["Communication", "Ownership"]

tags
string[]

Freeform labels for filtering

Reference URLs the AI can draw on

knowledge_base_extracted
string

AI-formatted job description in Markdown (the JD shown in the UI). description holds the raw text.

default_duration_minutes
integer

Default session length (default: 30)

default_difficulty
enum<string>

Default: intermediate

Available options:
beginner,
intermediate,
advanced,
expert,
adaptive
default_session_mode
enum<string>

Default: live_ai_interview

Available options:
live_ai_interview,
async_interview,
roleplay_simulation,
practice_session,
manual_review
visibility
enum<string>

Default: team

Available options:
private,
team,
organization

Response

Success

Last modified on July 26, 2026