# About Ribbon Source: https://docs.ribbon.ai/about-ribbon Ribbon is an **AI-powered voice interview platform** that helps hiring teams streamline screening. Candidates interview on their own schedule, and your team reviews transcripts, summaries, and evidence-backed scores to decide who moves forward. ## How it works 1. **Create a role** from a job description, posting link, template, or connected ATS job. 2. **Customize your interview** — review questions, scoring criteria, language, voice, and settings before publishing. 3. **Invite candidates** using a shareable link or invitations through Ribbon. 4. **Review and manage candidates** — explore results, update statuses, and share feedback with your team. ATS integrations are available on Scale and Enterprise plans. Other features may depend on your plan or account configuration. ## The candidate experience Interviews feel like a phone conversation and typically take around **20 minutes**, depending on the questions and responses. Candidates complete a sound check and interview without booking a time. A camera is needed if **Require Video** is enabled. # Ribbon MCP Source: https://docs.ribbon.ai/docs/mcp Ask Claude (or any MCP client) about your ATS pipeline in plain English. Ribbon MCP connects your ATS to AI assistants like Claude through the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, you can ask Claude things like "who applied to the Senior Engineer role this week?" and it will answer using live data from your ATS. Read-only for now — Claude can look things up, but can't change anything in your ATS. ## What you can ask Some example prompts that work out of the box: * *"Who applied to the Senior Engineer role this week?"* * *"Show me candidates in final-round interviews."* * *"Which open roles still haven't had a first-round interview?"* * *"What interviews are scheduled for tomorrow?"* * *"Find the candidate whose email is [jane@example.com](mailto:jane@example.com)."* ## Get set up **1. Create a Ribbon account** Sign up at [app.ribbon.ai](https://app.ribbon.ai). You'll need to be an admin on your org to connect an ATS or enable MCP. **2. Connect your ATS** Go to **Settings → Integrations**, pick your ATS (Ashby, Greenhouse, Lever, Workable, and many more via Kombo), and complete the authorization flow. Wait for the first sync to finish — Ribbon MCP can't read from an integration that's still setting up. See [Connecting your ATS](/knowledge-base/ats-and-integrations/connecting-ats) for more detail. **3. Connect Ribbon to Claude** In the left nav, click **Ribbon MCP**, then **Connect in Claude**. Claude will open in a new tab with Ribbon pre-filled as a custom connector. Approve access when prompted. That's it — Claude can now answer questions about your pipeline. ## What Claude can see Ribbon MCP exposes six read-only tools: | Tool | What it does | | - | - | | `list_jobs` | Open roles and their interview stages | | `list_applications` | The full pipeline — each application includes the candidate, job, interviews, and offers | | `list_candidates` | Candidates in your ATS; look up by name or email | | `list_interviews` | Upcoming and recent interviews | | `list_offers` | Outstanding and accepted offers | | `list_ats_users` | Recruiters, hiring managers, and interviewers in your ATS | Claude picks the right tool automatically based on what you ask. ## Use with ChatGPT, Cursor, or other clients The same server works with any MCP client. Instead of clicking "Connect in Claude", copy the server URL from the Ribbon MCP page into your client's MCP or Connectors settings: ``` https://app.ribbon.ai/be-api/mcp/ats ``` Your client will walk you through the same OAuth approval flow. ## Security and privacy * **Read-only.** No tool call can modify your ATS. * **Scoped to your org.** Claude only sees data for the Ribbon org you signed in to approve access. * **Revocable.** Disconnect the connector in Claude's settings at any time; the access token stops working immediately. * **OAuth 2.1 with PKCE.** Your credentials never leave Ribbon; Claude gets a short-lived access token, not your password. # Quick start: conducting general interviews Source: https://docs.ribbon.ai/docs/quick-start # 🎤 Conducting an interview This is a quick guide to conducting a general interview using Ribbon API. Let's create our first Interview - we're going to create a simple survey for McDonald's. We want to ask three questions: 1. When and where was the last time you visited McDonald's? 2. What's your favorite item on the McDonald's menu? 3. If you could introduce one new item to the menu, what would you introduce? ### Step 1: Create an Interview Flow First, create an **Interview Flow** with these questions, by making a `POST` request to `/interview-flows` ```bash bash theme={null} curl --request POST \ --url https://app.ribbon.ai/be-api/v1/interview-flows \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data @- <' \ --header 'content-type: application/json' \ --data ' { "interview_flow_id": "" } ' ``` ```bash bash theme={null} { "interview_id":"3346dfe0-0093-4fb8-9249-31d0c86d0210", "interview_link":"https://app.ribbon.ai/interview/api/12f4493d/3346dfe0-0093-4fb8-9249-31d0c86d0210" } ``` Visiting the `interview_link` above takes us here: ![](https://mintcdn.com/ribbon-198dd1e6/bcRhRPCi2Y1dJVxb/images/docs/6159e20d184bc2e4e6f0d4f49fdb7123c4a2cc8d67af048c9c647d24fbf79816-image.png?fit=max\&auto=format\&n=bcRhRPCi2Y1dJVxb\&q=85\&s=fe8f881e0758a2f4d65c53b6487ee844) That's it! Anyone who visits this link can complete your interview with our intelligent voice agent. Congratulations, you've created your first AI-powered interview. *** # 🔍 Retrieving interviews You can retrieve a list of completed and incomplete interviews by making a `GET` request to `/interviews` ```bash bash theme={null} curl --request GET \ --url https://app.ribbon.ai/be-api/v1/interviews \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` ```bash bash theme={null} const url = 'https://app.ribbon.ai/be-api/v1/interviews'; const options = { method: 'GET', headers: {accept: 'application/json', authorization: 'Bearer '} }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err)); ``` ```bash bash theme={null} { "interviews": [ { "interview_data": { "transcript": "", "transcript_with_timestamp": [ { "content": "Hello! How are you doing today?", "role": "agent", "words": [ { "end": 0.736684326171875, "start": 0.125105224609375, "word": "Hello!" } // ... word level timestamps ] } ], "interview_flow_id": "490c8ddf", "interview_id": "dabdf2a3-a680-41cf-a7e0-f2175e77c971", "status": "completed" } } /// ... more interviews ] } ``` *** [Getting Started with Ribbon API](/docs/getting-started) [Quick start: conducting recruitment interviews](/docs/quick-start-conducting-recruitment-interviews) # Quick start: conducting recruitment interviews Source: https://docs.ribbon.ai/docs/quick-start-conducting-recruitment-interviews # 💼 Conduct your first recruitment interview This is a quick guide to conducting a recruitment interview using Ribbon API. Recruitment interviews can be viewed within the Ribbon platform, giving you an easy way to manage candidates outside of the API. Let's create our first Interview - we're going to create a simple job interview for a Produce Stocker at Walmart. We want to ask three questions: 1. Are you eligible to work in the US? 2. When are you available to start? 3. Can you tell me about your past experience working within retail? ### Step 1: Create an Interview Flow First, create an **Interview Flow** with these questions, by making a `POST` request to `/interview-flows` with `interview_type` as `recruitment`. Here we also optionally set `is_video_enabled` to `true`. This will collect video from the candidate during the interview. ```bash bash theme={null} curl --request POST \ --url https://app.ribbon.ai/be-api/v1/interview-flows \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data @- <' \ --header 'content-type: application/json' \ --data ' { "interview_flow_id": "", "interviewee_email_address": "[email protected]", "interviewee_first_name": "Jane", "interviewee_last_name": "Doe" } ' ``` ```bash bash theme={null} { "interview_id":"a6163b74-f192-4cc0-9f2b-368bc2e20960", "interview_link":"https://app.ribbon.ai/interview/api/c3fe72a9/a6163b74-f192-4cc0-9f2b-368bc2e20960" } ``` Visiting the `interview_link` above takes us here: ![](https://mintcdn.com/ribbon-198dd1e6/bcRhRPCi2Y1dJVxb/images/docs/cdb01c053338a0ef97cd9b6e3e5ecc51f447033cbdd9896d3edbc2f01cc3ff82-image.png?fit=max\&auto=format\&n=bcRhRPCi2Y1dJVxb\&q=85\&s=7cec78f0a9b42cbe2ab58cf902aed5bb) Anyone who visits this link can complete your interview with our intelligent voice agent. Since this is a `recruitment` interview, we can also view and manage the interview from the platform: ![](https://mintcdn.com/ribbon-198dd1e6/bcRhRPCi2Y1dJVxb/images/docs/d71389bc3b01aab9c062cd8f64123986894613753c972848dede0fa4d24288d1-image.png?fit=max\&auto=format\&n=bcRhRPCi2Y1dJVxb\&q=85\&s=41569a38bed7b5354f88f317ec8e884d) That's it! Congratulations, you've conducted your first AI-powered interview. *** # 🔍 Retrieving interviews You can retrieve a list of completed and incomplete interviews by making a `GET` request to `/interviews` ```bash bash theme={null} curl --request GET \ --url https://app.ribbon.ai/be-api/v1/interviews \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` ```bash bash theme={null} const url = 'https://app.ribbon.ai/be-api/v1/interviews'; const options = { method: 'GET', headers: {accept: 'application/json', authorization: 'Bearer '} }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err)); ``` ```bash bash theme={null} { "interviews": [ { "interview_data": { "transcript": "", "transcript_with_timestamp": [ { "content": "Hello! How are you doing today?", "role": "agent", "words": [ { "end": 0.736684326171875, "start": 0.125105224609375, "word": "Hello!" } // ... word level timestamps ] } ], "interview_flow_id": "490c8ddf", "interview_id": "dabdf2a3-a680-41cf-a7e0-f2175e77c971", "status": "completed" } } /// ... more interviews ] } ``` *** [Quick start: conducting general interviews](/docs/quick-start) [Supported Languages](/docs/supported-languages) # Supported Languages Source: https://docs.ribbon.ai/docs/supported-languages Ribbon API supports multiple languages to accommodate diverse user bases across different regions. Each language code follows the format `{language}-{REGION}` using standard IETF language tags. | Language Code | Language | Region/Variant | | - | - | - | | en-US | English | United States | | de-DE | German | Germany | | es-419 | Spanish | Latin America | | hi-IN | Hindi | India | | ja-JP | Japanese | Japan | | pt-BR | Portuguese | Brazil | | fr-FR | French | France | | zh-CN | Chinese | China | | ko-KR | Korean | Korea | | vi-VN | Vietnamese | Vietnam | | th-TH | Thai | Thailand | | ar-AE | Arabic | United Arab Emirates | Is there a missing language you'd like us to add support for? Shoot me a message: [\[email protected\]](/cdn-cgi/l/email-protection#3c5d4e4f545d517c4e555e5e5352125d55) *** [Quick start: conducting recruitment interviews](/docs/quick-start-conducting-recruitment-interviews) [Supported Voices](/docs/supported-voices) # Supported Voices Source: https://docs.ribbon.ai/docs/supported-voices Ribbon API allows you to choose fine-tuned high-quality voices from leading providers. Each voice has been carefully chosen for clarity and natural expression. | Voice ID | Provider | Voice Name | Characteristics | | - | - | - | - | | 11labs-Anna | Eleven Labs | Anna | Professional female voice | | 11labs-Anthony | Eleven Labs | Anthony | Professional male voice | | 11labs-Kate | Eleven Labs | Kate | Warm female voice | | 11labs-Amy | Eleven Labs | Amy | Friendly female voice | | openai-Onyx | OpenAI | Onyx | Clear, authoritative voice | | openai-Shimmer | OpenAI | Shimmer | Bright, engaging voice | | IPgYtHTNLjC7Bq7IPHrm | Eleven Labs | Alexandre | Professional male voice with Quebecer accent | | UOIqAnmS11Reiei1Ytkc | Eleven Labs | Carolina | Friendly female voice with Spanish accent | Want to use your own custom voice? Get in touch: [\[email protected\]](/cdn-cgi/l/email-protection#afcedddcc7cec2efddc6cdcdc0c181cec6) *** [Supported Languages](/docs/supported-languages) [Webhooks](/docs/webhooks) # Webhooks Source: https://docs.ribbon.ai/docs/webhooks ### Specifying a webhook URL When creating an interview flow you can specify a `webhook_url`. This can be used to receive updates related to interviews. ```bash bash theme={null} curl --request POST \ --url https://app.ribbon.ai/be-api/v1/interview-flows \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "webhook_url": "https://example.com", "org_name": "Example Org Name", "title": "Example Title", "questions": [ "Example Question 1?", "Example Question 2?" ] } ' ``` ### Webhook Authentication You can specify a `webhook_secret_key` to verify that webhook requests are genuinely from Ribbon. When a secret key is configured, Ribbon will include an `X-Ribbon-Signature` header (also accepted as `x-ribbon-signature`) with each webhook request. The signature is an **HMAC-SHA256** hash of the **raw JSON request body**, using your webhook secret key, encoded as a **64-character hex string**. Ribbon never sends the secret key in the webhook request — you configure it in your interview settings and use the same value on your server to verify signatures. #### Example Given this webhook secret key configured in your interview settings: ``` myGoodSecret ``` And this raw request body: ```json json theme={null} {"interview_flow_id": "f6298c77", "interview_id": "e48f2a8f-e235-4e4c-b5f9-b2114d684bdc", "status": "completed", "interview_flow_name": "Team 1 interview", "event_type": "interview_processed", "interviewee_email_address": "anne@ribbon.ai", "interviewee_first_name": "Anne", "interviewee_last_name": "Anquetin0", "interview_link": "https://staging.ribbon.ai/recruit/interviews/f6298c77/a5bc36d2-c22c-4bae-9d08-0b941738924e"} ``` Ribbon sends a request with headers like: ``` Content-Type: application/json User-Agent: Ribbon-API-Webhook/1.0 x-ribbon-signature: bdae121de5d94dffe936ec3337b0395a4237a6d2433bbd0bc2941883e5667d18 ``` To verify, compute HMAC-SHA256 of the exact raw body string using `myGoodSecret` and compare the result to the header value. The signature must match byte-for-byte — use the raw request body as received, not a re-serialized or pretty-printed version of the JSON. #### Verifying the signature 1. Read the raw request body as a string (before parsing JSON) 2. Compute HMAC-SHA256 using your webhook secret key and the raw body 3. Hex-encode the result and compare it to the `X-Ribbon-Signature` header value using a constant-time comparison #### Code examples **Python** ```python python theme={null} import hmac import hashlib def verify_webhook_signature(body: str, secret: str, signature: str) -> bool: expected = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) body = '{"interview_flow_id": "f6298c77", "interview_id": "e48f2a8f-e235-4e4c-b5f9-b2114d684bdc", "status": "completed", "interview_flow_name": "Team 1 interview", "event_type": "interview_processed", "interviewee_email_address": "anne@ribbon.ai", "interviewee_first_name": "Anne", "interviewee_last_name": "Anquetin0", "interview_link": "https://staging.ribbon.ai/recruit/interviews/f6298c77/a5bc36d2-c22c-4bae-9d08-0b941738924e"}' secret = "myGoodSecret" signature = "bdae121de5d94dffe936ec3337b0395a4237a6d2433bbd0bc2941883e5667d18" verify_webhook_signature(body, secret, signature) # True ``` **TypeScript** ```typescript typescript theme={null} import crypto from "crypto"; function verifyWebhookSignature(body: string, secret: string, signature: string): boolean { const expected = crypto.createHmac("sha256", secret).update(body).digest("hex"); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } const body = '{"interview_flow_id": "f6298c77", "interview_id": "e48f2a8f-e235-4e4c-b5f9-b2114d684bdc", "status": "completed", "interview_flow_name": "Team 1 interview", "event_type": "interview_processed", "interviewee_email_address": "anne@ribbon.ai", "interviewee_first_name": "Anne", "interviewee_last_name": "Anquetin0", "interview_link": "https://staging.ribbon.ai/recruit/interviews/f6298c77/a5bc36d2-c22c-4bae-9d08-0b941738924e"}'; const secret = "myGoodSecret"; const signature = "bdae121de5d94dffe936ec3337b0395a4237a6d2433bbd0bc2941883e5667d18"; verifyWebhookSignature(body, secret, signature); // true ``` #### Security best practices * **Always verify signatures** in production to ensure webhooks are from Ribbon * **Use a strong, random secret key** (at least 32 characters recommended) * **Use constant-time comparison** functions (like `hmac.compare_digest` in Python or `crypto.timingSafeEqual` in TypeScript) to prevent timing attacks * **Keep your secret key secure** and never expose it in client-side code * **Verify the raw request body** — parsing and re-stringifying JSON will produce a different signature ### Static IP allowlisting By default, webhook requests may originate from dynamic IP addresses. If your server requires IP allowlisting, contact your Ribbon account team to enable **static IP webhook delivery** for your organization. When static IP delivery is enabled, all webhook requests to your endpoint will originate from a fixed egress IP address that you can add to your firewall allowlist. Ribbon still recommends verifying the `X-Ribbon-Signature` header on every request — signature verification is the most reliable way to authenticate webhooks. ### Webhook payload The webhook payload returns the `interview_flow_id`, `interview_id`, `interview_link` and `status`. ⚠️ `interviewee_email_address`, `interviewee_first_name` and `interviewee_last_name` will be null unless the candidate information were provided when creating the interview session (`POST interviews`) or if the candidate went through the full platform flow where candidate information is requested. We currently support three webhook event types: `interview_processed`, `video_processed`, and `candidate_status_updated` ### Webhook event types `interview_processed` This event occurs after an interview has been completed and the interview has been successfully processed and analyzed by Ribbon. If video was collected during the interview the **video will not be available yet**. #### Payload example ```bash bash theme={null} { "event_type": "interview_processed", "interview_flow_id": "d1a104e7", "interview_id": "7ada85b2-b8a6-4e4a-84ed-f1c25fa63843", "interview_link": "https://app.ribbon.ai/recruit/interviews/d1a104e7/9ae73ba9-1e8c-4d73-8454-478d7674ea97", "interview_flow_name": "Manager position role interview", "interviewee_email_address": "[email protected]", "interviewee_first_name": "John", "interviewee_last_name": "Doe", "status": "completed", } ``` `video_processed` This event only occurs if you are collecting video during the interview (`is_video_enabled` is `true`). The event is sent after video processing is complete and when the `video_url` is available. #### Payload example ```bash bash theme={null} { "event_type": "video_processed", "interview_flow_id": "d1a104e7", "interview_id": "7ada85b2-b8a6-4e4a-84ed-f1c25fa63843", "interview_link": "https://app.ribbon.ai/recruit/interviews/d1a104e7/9ae73ba9-1e8c-4d73-8454-478d7674ea97", "interview_flow_name": "Manager position role interview", "interviewee_email_address": "[email protected]", "interviewee_first_name": "John", "interviewee_last_name": "Doe", "status": "completed", } ``` `candidate_status_updated` This event occurs anytime a candidate’s status changes within the candidate pipeline (for example: shortlisted → accepted). The event includes both the previous status and the new status so you can track transitions precisely. #### Payload example ```bash bash theme={null} { "event_type": "candidate_status_updated", "interview_flow_id": "7b896044", "interview_flow_name": "Backend Engineer", "interviewee_email": "[email protected]", "new_status": "accepted", "previous_status": "shortlisted" } ``` ### Webhook event ordering You will explicitly always receive the events in this order: * `interview_processed` * `video_processed` *** [Supported Voices](/docs/supported-voices) # Overview Source: https://docs.ribbon.ai/index A quick start guide to creating your first interview. # What is Ribbon API? Ribbon API lets you create intelligent AI-powered voice interviews. To interview someone, all you have to do is share a link. Ribbon's AI interviewer can hold a natural and intelligent conversation with your interviewee. You can use the Ribbon API to create many types of interviews including: product interviews, surveys, recruitment interviews, health questionnaires, and much more. Use your imagination! *** # Concepts Ribbon API has two concepts: **Interview Flows** and **Interviews** **Interview Flows** are reusable sets of questions and context. They have two types: `general` (default) and `recruitment`. **Interviews** are created from **Interviews Flows**. Each interview has a one use session link. To interview someone, all you have to do is share the link! Once the interviewee has visited the interview link, the link is expired. *** # Interview type: General vs. Recruitment When creating an interview flow, you can choose between two interview types: `general` and `recruitment`. ## `general` type interviews All interviews are `general` type by default. This is a more generic type of interview suitable for multiple use cases. ## `recruitment` type interviews If you are screening a potential job candidate, you should use `recruitment` type interviews. These interviews are also displayed within the Ribbon platform giving you the opportunity to use Ribbon to view, score, and share the candidates more easily. *** # Authentication Create your first API key on the [Ribbon API console page](https://app.ribbon.ai/recruit/api-keys). When making an API call, add an Authorization header and set the API key as a Bearer Token: `Bearer ` You can test your API key by making a call to [/ping](/ribbon-public-api/ping) *** # Quick start guide There are two easy ways to get started depending on the type of interview you want to conduct: > **[General interviews](/docs/quick-start)** > > Suitable for product interviews, surveys, health questionnaires, and more. > **[Recruitment interviews](/docs/quick-start-conducting-recruitment-interviews)** > > For screening potential job candidates. # Connecting your ATS Source: https://docs.ribbon.ai/knowledge-base/ats-and-integrations/connecting-ats Connect your applicant tracking system to Ribbon. *Available on Scale and Enterprise plans.* Connecting an ATS helps you create roles from open jobs, import candidates, and synchronize supported hiring activity. ## Before you begin You’ll need **System Admin** access in Ribbon and may need an ATS administrator or API key. ## Connect your ATS 1. Click your team name in the sidebar and select **Organization settings**. 2. Under **General**, select **Integrations**. 3. Click **Connect ATS** and select your ATS. 4. Review permissions and follow the setup instructions. 5. Wait for the initial sync before creating ATS-linked roles. The initial sync may take **20 minutes to 72 hours**, depending on the ATS and data volume. Check connection status and last sync time under **Integrations**. Once connected, you can create roles from ATS jobs, map statuses to stages, and set up automated interview invitations. Need help? Email [support@ribbon.ai](mailto:support@ribbon.ai). # Creating a role from your ATS Source: https://docs.ribbon.ai/knowledge-base/ats-and-integrations/creating-role-from-ats Create a Ribbon interview using an open job in your connected ATS. Create a Ribbon interview from an open job in your connected ATS. Ribbon pulls in the job details and generates interview questions and scoring criteria for you to review. ## Before you begin Make sure your ATS is connected and its initial sync has finished. See [Connecting your ATS](/integrations/connecting-ats). ## Create your role 1. Click **+ New role**, then select **Create from ATS**. 2. Find and select the open job you'd like to use. 3. Click **Generate role**. 4. Review the role and company details, interview questions, and scoring criteria. Customize anything you'd like to change. 5. Choose your interviewer's language and voice, then review the interview settings. 6. On the **ATS** step, confirm the linked job and stage mapping. 7. Preview your interview, then click **Publish role**. Your Ribbon role is now linked to the ATS job, allowing candidate stages and interview summaries to sync back. ## Can't find your job? The initial sync can take **20 minutes to 72 hours**, depending on your ATS and the amount of data. Check that the sync has finished and that you have **Team admin** or **System admin** access. If the job still doesn't appear, contact your dedicated CSM or email [support@ribbon.ai](mailto:support@ribbon.ai). # Managing multiple requisitions with Multi-Req Source: https://docs.ribbon.ai/knowledge-base/ats-and-integrations/multi-req Link requisitions and locations under one Ribbon role. Multi-Req brings multiple requisitions or locations together under one Ribbon role, so your team can manage interviews and review candidates in one place. ## Link requisitions 1. Open the Ribbon role you'd like to use. 2. Go to **Settings → ATS**. 3. Click **Link a requisition**. 4. Search for and select the roles you'd like to link. Search by the role name as it appears in your ATS. 5. Click **Link**. You can link existing active Ribbon roles without recreating them, as well as new requisitions from your ATS. If your ATS stages are mapped, candidates and their stages continue to sync through the linked requisitions. ## How candidates are assigned to locations * **Invited through your ATS:** Candidates are automatically assigned to the location associated with their requisition. * **Using a shared Ribbon interview link:** Candidates choose their location before starting. ## Multi-Req or multiple hires? You don't need a separate requisition for every hire. A single Ribbon role can support multiple hires. Use Multi-Req when you want to bring separate requisitions or locations together under one role. # Adding candidates Source: https://docs.ribbon.ai/knowledge-base/candidates-and-outreach/adding-candidates Add candidates manually, from files, or from your ATS. Bring candidates into one place to track their progress and organize hiring. ## Add candidates to your role 1. Open the role and click **+ Add candidates**. 2. Choose **Add candidates manually**, **Import candidates from CSV**, **Import candidates from resume**, or **Import candidates from ATS** if connected. 3. Review their details. 4. Choose **Add only** to save candidates, or **Add and reach out** to prepare invitations. Adding a candidate does not automatically send an invitation. Candidates added without outreach appear under **Added** with the status **New lead**. Need help? [Contact support](mailto:support@ribbon.ai). # Setting up outreach automation Source: https://docs.ribbon.ai/knowledge-base/candidates-and-outreach/outreach-automation Automatically invite candidates when they reach a selected ATS stage. Automatically invite candidates to a Ribbon interview when they reach a selected stage in your ATS. You can choose your invitation channels, customize messages, and set reminders. ## Before you begin Connect your ATS and create a Ribbon role linked to the relevant job. You'll need **System admin** access to manage organization settings. ## Set up invitations 1. Open **Organization settings → Outreach Automation**. 2. Select your ATS connection and turn on **Send outreach to candidates**. 3. Choose the ATS stage that should trigger an invitation. 4. Customize messages for **email**, **SMS**, or **WhatsApp**. 5. Set when invitations can be sent and configure reminders. 6. Preview your settings, then save. ## Which candidates receive an invitation? Candidates who reach the selected stage **after automation is enabled** will receive an invitation. Candidates already in that stage won't be invited automatically. To invite them, select them in the role's candidate list and choose **Bulk actions → Send outreach**. If you need a hand, email [support@ribbon.ai](mailto:support@ribbon.ai). # Sending outreach and reminders Source: https://docs.ribbon.ai/knowledge-base/candidates-and-outreach/sending-outreach-reminders Invite candidates by email, SMS, or WhatsApp and manage reminders. Invite candidates through email, SMS, or WhatsApp without sending each message individually. Customize invitations and reminders to keep next steps clear. ## Before you begin Make sure candidates have been added to the role. See [Adding candidates](/candidates/adding-candidates). Email outreach needs an email address. SMS and WhatsApp need a phone number. Candidates must consent to SMS and can opt out of recruiting texts and reminders. ## Send outreach 1. Open the role and click **Send outreach**, or select candidates and choose **Bulk actions → Send outreach**. 2. Use filters and select the candidates you'd like to contact. 3. Choose **email**, **SMS**, **WhatsApp**, or a combination. 4. Customize the messages, including your company, role, expected interview length, and deadline. 5. Set message timing and reminders. 6. Review previews and recipients, then send. ## Check your outreach Open the role's **Outreach** tab to review messages, channels, recipient counts, and send dates. **Not sent yet** means outreach is set up but hasn't been sent. The candidate list separates **Added**, **Invited**, **Completed interviews**, and **Incomplete interview attempts** to help you see who may need attention. ## Automate invitations through your ATS You can also invite candidates automatically when they reach a selected ATS stage. See [Setting up outreach automation](https://app.mintlify.com/ribbon-198dd1e6/ribbon-198dd1e6/~/Setting-up-outreach-automation-8c64431f-0799-4c03-b862-10cb097ea4ee). Candidates already at that stage when automation is enabled need manual outreach. # Closing and reopening a role Source: https://docs.ribbon.ai/knowledge-base/managing-roles-and-interviews/closing-reopening Pause or schedule interviews without losing completed results. Ready to pause interviews or wrap up hiring? Closing a role stops new interviews while preserving information already collected. ## Close a role 1. Open the role. 2. Click the status dropdown in the top left. 3. Select **Closed** and confirm. 4. Check the interview link in a new window to verify candidates can no longer start. Pause outreach or ATS automations that direct candidates to the closed role. ## Schedule a closing date 1. Open the role’s status dropdown. 2. Select **Schedule Close**. 3. Choose the date and time and confirm. The time uses your current time zone. ## Reopen a role Change the status to **Accepting interviews**. Your existing interview link will work again. Closing is reversible. If you need a separate hiring pipeline, duplicate the role instead. # Tracking interview completion with Funnel Source: https://docs.ribbon.ai/knowledge-base/managing-roles-and-interviews/interview-funnel See where candidates are in the interview process and identify drop-off. The **Funnel** tracks candidates from invitation to interview completion, helping you focus your follow-up. ## Open the Funnel 1. Open the role you want to review. 2. Select **Funnel**. 3. Choose **7 days**, **30 days**, or **90 days**. 4. Review stage counts and conversion percentages. ## What each stage means * **Invited:** Candidates with a recorded interview invitation. * **Landed:** Candidates who opened the interview page, even if they didn't start. * **Started:** Candidates who reached the interview call after the sound check. * **Completed:** Finished interview attempts, including those ended early by a knockout question. A completed attempt doesn't necessarily mean the candidate answered every question or passed the interview. ## Investigate drop-off The Funnel shows where candidates stop, but not why. * **Invited to Landed:** Check invitation clarity, contact details, outreach timing, and reports of missing messages. * **Landed to Started:** Review intake requirements, device or video requirements, and sound check. Consider whether candidates need technical help or an accommodation. * **Started to Completed:** Review **Incomplete interview attempts**, technical issues, questions, and interview length. Compare the same date range when reviewing trends. ## Follow up with candidates Select candidates from the role's candidate list for a reminder or support. Check the **Outreach** tab for previous messages before reaching out again. # Reviewing Integrity Monitor and verification signals Source: https://docs.ribbon.ai/knowledge-base/scoring-and-evaluating-candidates/integrity-monitor Understand verification flags and record your team's assessment. The **Verification** tab highlights signals that may need a closer look. A flag is a prompt for review, not proof of misconduct or an automatic hiring decision. ## Review Integrity Monitor signals Integrity Monitor reviews video interviews for moments such as extended lookaways or another person appearing in frame. It works alongside checks of the audio environment, response timing, and input consistency. 1. Open the candidate's profile and select **Verification**. 2. Review **Integrity monitoring**. A warning or **Concern detected** means a signal needs attention. 3. Expand the signal to see its timestamp. 4. Watch that moment and read the surrounding transcript. 5. Complete **Team review** to record your assessment. 6. Add context in **Notes and comments**. Ribbon does not reject a candidate based on an integrity flag. ## Review verification signals Below Integrity monitoring, check **Verification signals**. These may include email risk, phone validity, location consistency, and VPN usage. Read the explanation and consider the candidate's circumstances. A VPN or location mismatch can have an ordinary explanation, particularly for remote roles. ## Complete a Team review 1. Review flagged signals alongside the interview and transcript. 2. Select **Looks genuine** or **Suspicious**. 3. Click **Save review**. Your saved review overrides Ribbon's automated flags and is visible to your team. Team review is optional. The presence or absence of a signal doesn't establish someone's identity or guarantee whether outside assistance occurred. # Reviewing a candidate’s interview Source: https://docs.ribbon.ai/knowledge-base/scoring-and-evaluating-candidates/reviewing-interviews Review summaries, scores, recordings, and notes. A candidate profile brings together interview results, scores, documents, and team notes. ## Open the candidate profile Open the role and select a candidate in **All candidates**. Search by name or email if needed and check filters. ## Review their interview 1. Read the **Summary** for strengths, experience, and gaps. 2. Open **Scorecard** to review overall and individual rubric scores. 3. Expand criteria to inspect supporting quotes and timestamps. Select **Jump to moment** where available. 4. Use **Interview playback** or **Show transcript** to review answers. 5. Check **Questions**, **Documents**, and **Verification** for additional context. A resume score may appear when a resume is available. Consider all evidence together rather than relying on a score alone. ## Collaborate with your team Comment on transcript excerpts or add notes under **Notes and comments**. Notes are visible to people with role access, not candidates. Review evidence against your hiring criteria before updating status. On ATS-linked roles, mapped status changes may also update your ATS. # Sharing and downloading candidate results Source: https://docs.ribbon.ai/knowledge-base/scoring-and-evaluating-candidates/sharing-downloading-results Share candidate profiles, download interview files, and export candidate lists. Share a candidate's profile with a hiring manager, download individual interview files, or export a candidate list for reporting. ## Share a candidate profile 1. Open the candidate's profile. 2. Click **Shared** in the top right. 3. Select **Anyone with link (180 days)**. 4. Click **Copy link** and share it through your organization's approved channel. The link gives view-only access to the candidate's available video, transcript, summary, and scores. It doesn't let reviewers edit the profile or view other candidates. **Anyone with the link can view the profile**, so share it carefully. ## Stop sharing Open **Shared** again and switch to **Only my team** to restrict access to your Ribbon organization. External links otherwise expire after **180 days**. ## Download an interview file 1. Open the candidate's profile. 2. Click the **three dots** beside **Send message**. 3. Choose **Download video**, **Download transcript**, or **Download candidate summary**, as available. 4. Save the file in a location approved by your organization. ## Export a candidate list 1. Open the role's candidate list and apply any filters. 2. Select the candidates to export. 3. Choose **Bulk actions → Export selected**. 4. Select the columns and click **Export candidates**. Ribbon prepares the CSV and emails a download link titled **Your export is ready to download**. The link expires after **24 hours**. A candidate-list export contains your selected CSV columns. Use the profile's download menu for individual interview files. # Team roles and permissions Source: https://docs.ribbon.ai/knowledge-base/settings-and-team-management/team-permissions Manage who can access roles, candidates, and settings. Ribbon offers three common permission levels: * **Member:** Work with assigned roles and review candidates. * **Team Admin:** Manage members in their sub-team and import requisitions. * **System Admin:** Manage organization-wide settings, ATS connections, billing, and users. ## Update a teammate’s role 1. Go to **Settings → Teams and Members**. 2. Find the person in **Directory**. 3. Use the **Seat** dropdown to change their role. ## Inviting teammates Use **Settings → Teams and Members** to invite users. If invitations don’t arrive, ask IT to allow emails from `ribbon.ai`. For SSO, IT may need to assign the user to Ribbon in the identity provider. If an invite fails, log out, clear Ribbon cookies, and reopen the link. Contact [support@ribbon.ai](mailto:support@ribbon.ai) if you’re still stuck. # Managing interview retries and technical resets Source: https://docs.ribbon.ai/knowledge-base/troubleshooting-and-support/interview-retries-resets Understand retry limits and help candidates restart after technical issues. Retries let a candidate take the same interview again. Your settings determine how many retries are allowed, so a candidate may need your help after a technical issue. **Only the most recent attempt is available in Ribbon. A new attempt replaces the previous one.** ## Set your retry policy 1. Open **Organization settings → Advanced** under Interviews. 2. Find **Limit interview retries**. 3. Leave it **off** for unlimited retries, or turn it **on** and choose no retries or a limit from **1 to 10**. 4. Click **Save**. No retries creates a one-attempt experience. If the setting is **Flexible**, you can change it for an individual role under **Settings → Advanced**. Settings enforced at the organization or team level must be changed there. ## Help after a technical issue Ask the candidate to reopen their original interview link. Whether they can retry depends on the role's status and retry settings. Review their profile and any **Incomplete interview attempts** before resetting anything. A reset isn't needed for every interruption. ## Reset a blocked candidate If a technical issue has left the candidate blocked by the retry limit: 1. Confirm the candidate and role are correct. 2. Download any interview records you need to keep before deleting. 3. Open the candidate's profile and click the **three dots** beside **Send message**. 4. Choose **Delete interview and send retry email**. This deletes the existing interview and emails the candidate a fresh link. ## What does deletion remove? Both deletion options remove the interview's **recording, transcript, scores, and summary**. Deletion can't be undone. * **Delete interview:** Removes the interview without sending a new invitation. * **Delete interview and send retry email:** Removes it and sends a fresh invitation. For a data-removal request, follow your organization's approved process and confirm the scope before deleting. If the candidate still can't continue, email [support@ribbon.ai](mailto:support@ribbon.ai) with their email address, interview link, and a short description of the issue. # Managing your subscription Source: https://docs.ribbon.ai/managing-your-subscription You can review your plan, track usage, and manage billing from **Organization settings → Plan and Usage**. You'll need system admin access to open organization settings. ## View your plan and usage 1. Click your organization name in the top-left corner of Ribbon and select **Organization settings**. 2. Open **Plan and Usage**. 3. Review your current plan, role and interview limits, and any interview overage. ## Upgrade or change your plan Need more active roles, interviews, or access to additional features? Reach out to your customer contact or email [support@ribbon.ai](mailto:support@ribbon.ai). We’ll help you find the right plan and confirm the pricing and timing of the change. ## Update your billing information Open **Organization settings → Plan and Usage** to access your available billing and payment settings. Update the details you need to change, then save and check that your billing information is correct. If you can’t update a payment method or invoice detail, email [support@ribbon.ai](mailto:support@ribbon.ai). Please don’t send full card details by email. ## Cancel your subscription 1. Open **Organization settings → Plan and Usage**. 2. Select the cancellation option. 3. Review the cancellation date and any remaining access, then confirm. Before your access ends, download any candidate videos, transcripts, or summaries you’d like to keep from the three-dot menu on each candidate’s profile. If you don’t see a cancellation option or have a contracted plan, email [support@ribbon.ai](mailto:support@ribbon.ai) for help with the next steps. ## Questions about a charge? For invoice, payment, or refund questions, email [support@ribbon.ai](mailto:support@ribbon.ai) with your organization name, invoice number if available, and a short description of the issue. We’ll review your account and help clarify the next steps. # Delete interview flow Source: https://docs.ribbon.ai/ribbon-public-api/delete-interview-flow delete /v1/interview-flows/{interview_flow_id} Delete an interview flow. # Get interview Source: https://docs.ribbon.ai/ribbon-public-api/get-interview get /v1/interviews/{interview_id} Retrieve a specific interview session. # Get interview flow Source: https://docs.ribbon.ai/ribbon-public-api/get-interview-flow get /v1/interview-flows/{interview_flow_id} Retrieve a specific interview flow. # Get interview flows Source: https://docs.ribbon.ai/ribbon-public-api/get-interview-flows get /v1/interview-flows Retrieve all interview flows. If team_id is not provided, returns interview flows for all teams in the organization. # Get interviews Source: https://docs.ribbon.ai/ribbon-public-api/get-interviews get /v1/interviews Retrieve all interview sessions. If team_id is not provided, returns interviews for all teams in the organization. Narrow the result with interview_flow_id (a single role) and/or ended_after / ended_before (when the interview finished) — polling with ended_after set to the last ended_at you saw returns only interviews completed since then. # Get team members Source: https://docs.ribbon.ai/ribbon-public-api/get-team-members get /v1/team-members Retrieve team members in the organization. Use the returned id as assigned_recruiter_id when creating an interview. If team_id is not provided, returns members for all teams in the organization. limit defaults to the maximum page size, so omitting it returns every member. # Get teams Source: https://docs.ribbon.ai/ribbon-public-api/get-teams get /v1/teams Retrieve teams in the organization. limit defaults to the maximum page size, so omitting it returns every team. # Ping Source: https://docs.ribbon.ai/ribbon-public-api/ping get /v1/ping Send a dummy request. # Post interview Source: https://docs.ribbon.ai/ribbon-public-api/post-interview post /v1/interviews Create an interview session. The interview will be created in the same team as the interview flow. # Post interview flow Source: https://docs.ribbon.ai/ribbon-public-api/post-interview-flow post /v1/interview-flows Create an interview flow. If team_id is not provided, defaults to the oldest team in the organization. # Revoke Access to Interview Recordings Source: https://docs.ribbon.ai/ribbon-public-api/revoke-access-to-interview-recordings delete /v1/interviews/{interview_id} Revoke access to video and audio recordings for an interview. # Frequently asked questions Source: https://docs.ribbon.ai/untitled-page-3 Find quick answers to common questions about hiring with Ribbon. > **What is Ribbon?** > > Ribbon is an AI-powered interview platform that helps your team learn more about candidates before moving them to the next stage. Candidates complete a voice interview on their own time, and you can review their responses, summaries, and scores afterward. > **How do I create a role?** > > Go to **Roles** and follow the prompts to create a role, add your interview questions, and configure your settings. If your organization has an ATS integration, you can also create a role from your ATS. > **How do I invite candidates to an interview?** > > You can share the role’s interview link or send outreach directly from Ribbon. > > To send outreach, select the candidates, open **Bulk actions**, and choose **Send outreach**. Follow the prompts to choose your outreach channel and send your invitations. > **Does adding a candidate automatically send an invitation?** > > Adding a candidate to Ribbon doesn’t automatically send an interview invitation. You’ll need to send outreach or have an outreach automation configured. > **Can I automate interview invitations through my ATS?** > > If your organization has an ATS integration, you can configure outreach to send when a candidate enters a selected stage. > > Candidates already in that stage when you enable the automation won’t be invited automatically. You can send outreach to those candidates manually. > **Can I use one interview for multiple requisitions or locations?** > > Yes! Multi-Req lets you link multiple requisitions or locations under one Ribbon role, so your team can use the same interview and review candidates in one place. > > Open the role, go to **Settings → ATS**, and click **Link a requisition**. Search for and select the requisitions you’d like to include, then click **Link**. You can link requisitions that haven’t been added to Ribbon yet, as well as existing active Ribbon roles. > **Do candidates need to schedule their interviews?** > > Candidates can complete their interviews whenever works best for them, before any deadline you’ve set. There’s no need to coordinate a time with your team. > **Can I require candidates to turn on their camera?** > > Yes. Enable **Require Video** in the role’s interview settings to require candidates to use their camera. They’ll be prompted to enable it before starting. > **What happens if a candidate’s interview is interrupted?** > > Candidates have up to one hour to return through their original interview link and resume. > > After that window, the interview is submitted with the responses they completed, and your team can see that it’s incomplete. > **Who handles requests to restart or retake an interview?** > > Your hiring team handles interview reset requests. Candidates should contact you directly if they need another attempt. Ribbon support can help troubleshoot technical issues. > **Where can I review completed interviews?** > > Open the role and select a candidate to review their interview summary, scores, and transcript. Video is also available for interviews recorded with video enabled. > **Can I share candidates with someone outside Ribbon?** > > Yes! **Shortlists** let you share selected candidates from any role with someone outside your Ribbon account. > > Anyone with the link can view the shortlist for 180 days, including candidate summaries and scorecards. Keep this in mind when choosing who to share the link with. > **Where can I check my plan and interview usage?** > > Go to **Organization settings → Plan & Usage** to review your subscription and usage. For billing options, select **Manage Billing**. > **How do I report a bug or request a feature?** > > Open the support messenger in Ribbon and let us know what you’re experiencing or what you’d like to see. > > For a technical issue, include the affected role or candidate link, what happened, and any screenshots or error messages. For a feature request, tell us what you’re trying to accomplish and how it would help your team. # Welcome to Ribbon Source: https://docs.ribbon.ai/welcome Everything you need to get started, manage your hiring, and make the most of Ribbon. Whether you’re setting up your first interview or exploring a new feature, we’re here to help. ## How can we help? > **[Get started](/getting-started)** > > Get to know Ribbon and set up your first role and interview. > **[Manage your roles](/managing-roles)** > > Create and update roles, customize interviews, and manage requisitions. > **[Invite candidates](/candidate-outreach)** > > Share interview links, send outreach, and automate invitations. > **[Review interviews](/reviewing-candidates)** > > Explore candidate responses, summaries, and scorecards. > **[Connect your ATS](/ats-integrations)** > > Connect your hiring tools and keep your workflow moving. > **[Manage your account](/account-settings)** > > Find help with team access, organization settings, and billing. ## A few helpful places to start * **Creating your first role:** Build an interview that helps you learn what matters for your team. * **Setting up automated outreach:** Invite candidates when they reach the right stage in your ATS. * **Using Multi-Req:** Bring multiple requisitions or locations together under one role. * **Sharing a shortlist:** Give others an easy way to review selected candidates. ## Have a quick question? Visit our [frequently asked questions](/faq) for answers about interview invitations, candidate reviews, account settings, and more. ## Need a hand? Open the support messenger in Ribbon to chat with our team. Whether you have a question, run into an issue, or want help getting set up, we’re happy to help.