Skip to main content
POST
/
v1
/
interview-flows
Post interview flow
curl --request POST \
  --url https://app.ribbon.ai/be-api/v1/interview-flows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "org_name": "<string>",
  "title": "<string>",
  "questions": [
    "<string>"
  ],
  "voice_id": "11labs-Kate",
  "language": "en-US",
  "company_logo_url": null,
  "additional_info": null,
  "additional_instructions": null,
  "interview_type": "general",
  "is_video_enabled": false,
  "is_doc_upload_enabled": false,
  "redirect_url": null,
  "webhook_url": null,
  "webhook_secret_key": null,
  "intro": null,
  "outro": null
}
'
{
  "interview_flow_id": "<string>"
}

Authorizations

​
Authorization
string
header
required

Provide your API key UUID in the 'Authorization' header prefixed with 'Bearer '. Example: 'Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000'

Body

application/json
​
org_name
string
required

The name of the organization requesting the interview.

​
title
string
required

The title for the interview.

​
questions
string[]
required

A list of questions to include in the interview.

​
voice_id
any | null
default:11labs-Kate

The voice ID to be used for the interview agent.

Available options:
11labs-Anna,
openai-Onyx,
openai-Shimmer,
11labs-Anthony,
11labs-Kate,
11labs-Amy,
IPgYtHTNLjC7Bq7IPHrm,
UOIqAnmS11Reiei1Ytkc,
​
language
any | null
default:en-US

The language of the interview flow.

Available options:
en-US,
de-DE,
es-419,
hi-IN,
ja-JP,
pt-BR,
fr-FR,
zh-CN,
ko-KR,
vi-VN,
th-TH,
ar-AE,
​
company_logo_url
string | null

Optional URL for the company's logo. If not provided, the Ribbon logo will be shown.

​
additional_info
string | null

Extra contextual information relevant to the interview. This can include background details, facts, or data points that the AI may use to enrich its questions or answers. For example: research focus, demographics or situational context.

​
additional_instructions
string | null

Guidelines on how the AI should behave during the interview. For example, adjust tone formality, avoid certain topics, or follow specific communication rules.

​
interview_type
enum<string> | null
default:general

The type of interview.

Available options:
recruitment,
general,
​
is_video_enabled
boolean | null
default:false

Whether the interview is video recorded or not.

​
is_doc_upload_enabled
boolean | null
default:false

Whether candidates can add resumes or other documents during the interview or not.

​
redirect_url
string | null

The URL where interviewee will be redirected after completing the interview. Make sure you're using the full URL, including https://

​
webhook_url
string | null

The URL that will be called after interview processing is complete. The payload will contain interview_flow_id, interview_id, and status.

​
webhook_secret_key
string | null

A secret key used to sign webhook payloads. When set, an X-Ribbon-Signature header containing an HMAC-SHA256 signature will be included with each webhook request.

​
intro
string | null

Introductory text spoken by the AI interviewer at the beginning of the interview.

​
outro
string | null

Concluding text spoken by the AI interviewer at the end of the interview.

Response

OK

​
interview_flow_id
string
required

The ID of the interview flow.