Create an interview for a candidate and return an access token URL

Authorizations

Authorization

string

header

required

Supabase JWT access token, passed as Authorization: Bearer <token>.

Body

application/json

candidate_name

string

required

Candidate full name.

Minimum string length: 1

Example:

"John"

candidate_email

string

required

Candidate email (used as auth identity).

Minimum string length: 1

Example:

"peterson6@hello.com"

candidate_country_code

string

required

ISO country code of the candidate.

Minimum string length: 1

Example:

"HR"

candidate_resume

string

required

Candidate resume parsed text.

Minimum string length: 1

Example:

"Curriculum Vitae ..."

position_def_set_id

string | null

Existing position_def_set id. When provided, the position is looked up instead of created, and position_name/position_location/position_country_code/mojito_language_code become optional.

Example:

"00000000-0000-0000-0000-000000000000"

position_external_id

string | null

External position code used to look up an existing position.

Example:

"JOB-123"

interview_template_id

string | null

Interview template id to base the interview on. Defaults to the platform template when omitted.

Example:

"5d8ea38b-eec4-4866-aa6c-b2ea5bc6e45b"

merchant_id

string | null

Merchant id. Only honoured for admin / sub-merchant tokens; otherwise the token merchant is used.

Example:

"28106cba-1c27-4e53-b149-32113e5e8e31"

position_name

string | null

Position / job title. Required when position_def_set_id is not provided.

Example:

"Entry level coffee boy"

position_location

string | null

Position location. Required when position_def_set_id is not provided.

Example:

"remote"

position_country_code

string | null

ISO country code of the position. Required when position_def_set_id is not provided.

Example:

"SK"

mojito_language_code

enum<string> | null

Interview language code (one of the platform-languages.json codes). Required when position_def_set_id is not provided.

Available options:

ar,

bg,

zh,

hr,

cs,

da,

nl,

en,

fil,

fi,

fr,

de,

el,

hi,

hu,

id,

it,

ja,

ko,

ms,

no,

pl,

pt,

br,

ro,

ru,

sk,

es,

sv,

ta,

th,

tr,

uk,

vi

Example:

"en"

position_description

string | null

Short position description.

position_description_long

string | null

Full / long position description.

candidate_external_id

string | null

External candidate id stored on the profile.

candidate_linkedin_url

string | null

Candidate LinkedIn URL.

candidate_video_introduction

enum<string> | null

Whether a candidate video introduction is optional or required.

Available options:

optional,

required

interview_attempts

number | null

Number of allowed interview attempts (1-20).

Required range: 1 <= x <= 20

Example:

3

seniority_level

enum<string> | null

Seniority level of the position. Auto-detected when omitted.

Available options:

entry-level,

intermediate,

senior,

managerial,

director,

executive

result_view

enum<string> | null

How interview results are shown to the candidate. Defaults to minimal.

Available options:

none,

minimal,

minimal_with_score,

advanced,

full,

full_expand_scores

custom_scoring

object

Optional custom scoring overrides merged with platform defaults.

Show child attributes

use_enhanced_expectations

boolean | null

Reserved flag for enhanced candidate expectations generation.

include_rapport_question

boolean | null

Include an opening rapport question. Defaults to false.

include_closing_prompt

boolean | null

Include a closing prompt. Defaults to true.

instructional_video

boolean | null

Show an instructional video before the interview. Defaults to false.

instructional_video_custom_text

string | null

Custom text shown with the instructional video.

welcome_message

string | null

Custom welcome message for the interview.

thank_you_message

string | null

Custom thank-you message shown after the interview.

max_duration

number | null

Maximum interview duration used to scale generated questions.

is_embedded

boolean | null

Set true when the interview will be embedded as an iframe on an external page. Ensures an embed key exists and returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed.

Response

Candidate enrolled. Decision status, ids, and a tokenised interview URL.

Result of creating (or resolving) the position and enrolling the candidate. Fields present depend on the decision branch.

status

enum<string>

required

Decision / lifecycle status for the candidate against this position.

Available options:

ai_accept,

recruiter_accept,

recruiter_action,

ai_reject,

recruiter_reject,

already-applied

interview_url

string

required

URL the candidate should open to continue.

position_def_set_id

string

Created/resolved position id.

interview_def_set_id

string

Created/resolved interview definition set id.

profile_interview_id

string

Candidate profile_interview id.

reason

string

Human-readable reason, present on reject / already-applied branches.

embed_id

string

Embed id, present only when is_embedded=true.

embed_signing_key

string

Embed signing key, present only when is_embedded=true.