add_candidates
ChatGPTAdd candidates to an open role's Ribbon pipeline without contacting them. They start as new leads unless you pass status or ats_stage_mapping_id, which apply only to the candidates this call adds; use update_candidate_status for candidates already in the role. With source ats, pass ats_application_id values (from list_applications): Ribbon reads each applicant's name, email and phone from the ATS, keeps the candidate linked to that application so update_candidate_status can move them, and grabs their resume. The application's job must be linked to the role. Applications that can't be imported are listed in failed; the rest are still added. Existing candidates and duplicate emails are skipped, so repeating the same call is safe. When the role's new-lead status is linked to an ATS stage, Ribbon also synchronizes newly added candidates to that stage. This tool never sends outreach; use send_outreach separately.
create_shortlist
ChatGPTMake a named shortlist of people, so a recruiter or hiring manager can review just those candidates on one page. Returns the shortlist's id and its URL in Ribbon; put that URL in whatever you send, rather than listing the candidates again. Pass the candidates' email addresses, from find_candidates or get_candidate. A shortlist holds people, not applications: everyone you name goes on it, whether or not they are on the role you are working from, so nothing is silently dropped. The shortlist shows each person's most recent interview in the organisation. Everyone on the role's team can open the shortlist; it has no public link until a person turns one on in the app, which this tool deliberately cannot do. Each call creates a NEW shortlist, so never repeat a call after a lost response — and to put more people on a shortlist you already made, do not create a second one.
find_candidates
ChatGPTFind one role's candidates by where they stand now, by what changed for them in a time window, or both. Each result is one candidate with their current status, when they were added to the pipeline, and interview scores (no transcript). The email in each result is what send_outreach takes. Each result also lists the candidate's applications in this role, one per requisition, each with its own member_status, ATS stage, candidate_application_id and a candidate on more than one requisition can be at a different stage on each. update_candidate_status takes the candidate_application_id of each application to move. mode 'current' (where they stand): member_statuses, interviewed and added_after / added_before filter on the candidate's current state; results come longest in the pipeline first. Use this when the trigger is something that has NOT happened, which no change records. For candidates invited three or more days ago who still haven't interviewed, pass member_statuses ['invited'], interviewed false, and added_before three days before now. added_after / added_before bound when the candidate joined the role's pipeline, not when they were invited or contacted; this tool does not know what outreach a candidate has received. mode 'changed' (what changed): pass changed_since and changed_until (both required) to get only candidates something happened to in that window, oldest change first, each with last_change. When your instructions ask what happened since the last run, pass window_start_inclusive as changed_since and window_end_exclusive as changed_until from the Run context. Exactly two kinds of change are recorded, and nothing else. interview_scored: a call's first scoring finished, which is later than when the interview ended; rescores are not recorded, and neither are calls on roles with no scoring criteria. stage_changed: the candidate's Ribbon stage changed from from_status to to_status, whoever moved them (a recruiter, the ATS sync, or an agent, including you). last_change.moved_by says who: user (a person in Ribbon), agent, ats, system, or null when unknown; moved_by_you is true only for a move you made yourself, so you can skip your own changes. Each move is recorded per application: last_change.candidate_application_id is the application that moved (see the candidate's applications), and from_status / to_status are that application's. The candidate's current status can differ from to_status if they moved again. Candidates being added, outreach or messages, interviews starting or ending, and ATS changes that leave the Ribbon stage as it was are not recorded, so never wait for or act on any other kind. When the trigger is an interview being scored, use changed_since / changed_until rather than checking candidates' current stage, so a late score is not missed. Each read also reaches back a few minutes before changed_since to catch changes that were saved late, so a change can be returned by more than one run; last_change.change_id identifies it. A candidate who changed more than once appears once on a page, with the latest of those changes, and appears again on a later page only for a later change. Both: in mode 'changed' the state filters also apply, against the candidate's current state. For candidates scored since the last run who are still at interviewed, pass mode 'changed', change_kinds ['interview_scored'] and member_statuses ['interviewed'] with the window. A page can come back short, even empty, with has_more true; keep paging with next_cursor, passing the same filters, until has_more is false. For transcripts use list_interview_transcripts.
get_candidate
ChatGPTEverything Ribbon has on one candidate, looked up by email address: one result per role they are in, newest interview first, each with their status, their applications (with the candidate_application_id that update_candidate_status takes), scores, summary and transcript. Candidates who have not interviewed yet are included, with no transcript. Spans all of the org's roles unless you pass interview_flow_id to narrow it to one.
list_applications
ChatGPTList applications (candidate-for-job pipeline entries). Each application embeds candidate, job, interviews, and offers so a single call can answer most pipeline questions.
list_ats_integrations
ChatGPTHow the org's ATS is set up in Ribbon: every connected ATS integration with its linked stages, its default completion stage and its outreach stage. A linked stage is an ATS stage linked to a Ribbon status, or a custom ATS stage with a null status that candidates can sit in without changing their Ribbon status. default_completion_stage is where a candidate's ATS application moves after their interview unless the role sets its own: for an ATS with linked stages it is the stage linked to Interviewed (source interviewed_link), and with no such link nothing moves; for other ATSs it is the integration's completion setting (source integration_setting). outreach_stage is the ATS stage that starts Ribbon outreach when a candidate enters it. ats_account_token is the integration_id the ATS tools take. Call this when a recruiter asks which ATS they use or how their stages are linked. It describes the org's setup, not a role: a job can lack some of its integration's stages, and list_stages lists what a role's candidates can be moved to. Each integration has: ats_account_token, ats, display_name, supports_linked_stages, linked_stages, default_completion_stage, outreach_stage. Each linked_stages entry on an integration has: ats_stage_mapping_id, ats_stage, status, color.
list_ats_users
ChatGPTList users in the ATS (recruiters, hiring managers, interviewers).
list_candidates
ChatGPTList candidates from the connected ATS. Supports filtering by email, name, and job.
list_interview_flows
ChatGPTList the roles this org runs AI interviews for. Defaults to open roles. Start here: every other Ribbon tool takes an interview_flow_id from this list. Rows imported from an ATS also carry ats_account_token and ats_integration_job_id. To query ATS tools for a linked role, pass ats_account_token as integration_id and ats_integration_job_id in job_ids. Job ids alone do not select the ATS integration.
list_interview_scores
ChatGPTThe interview scores configured on a role (what each interview is scored on), in display order. Read this before calling update_interview_scores so you send back the existing score ids instead of creating duplicates.
list_interview_transcripts
ChatGPTInterview transcripts and scores for one role, most recently interviewed first. Filter by pipeline status (member_statuses), by candidate name (candidate_name_contains), and/or by when the interview finished (interviewed_after / interviewed_before) — pass interviewed_after with the timestamp of the last transcript you saw to pull only new ones. Candidates who haven't interviewed yet are excluded unless you ask for them. This is also how you turn a candidate name into the email address the write tools take.
list_interviews
ChatGPTList scheduled interviews.
list_jobs
ChatGPTList jobs from the connected ATS. Defaults to OPEN jobs. Supports filtering by name and status.
list_offers
ChatGPTList offers extended to candidates.
list_org_members
ChatGPTThe people in this organization who have a Ribbon account, alphabetically: their name, their email address, and whether they are a system admin. is_you marks the member whose account this connection belongs to. A member with no email address on file is not listed. This is the whole org, not one team: members of every team in it. Each org_member has: email, full_name, is_system_admin, is_you.
list_stages
ChatGPTEvery stage a candidate on this role can be moved to. statuses lists the Ribbon statuses. jobs lists the role's ATS jobs, each with its ats_stages: an ATS stage with the Ribbon status it is linked to, or a null status for a custom ATS stage. Stages can differ between jobs, so pass candidate_application_ids (from find_candidates) to get the jobs those applications are on, including a job since unlinked from the role; without them, jobs lists the jobs linked to the role now. ribbon_only_candidate_application_ids are on no ATS job and only take Ribbon statuses. Call this when you are given a stage name: match it against both the Ribbon statuses and the ATS stage names. To move candidates, pass update_candidate_status either a status (an application moves to the ATS stage linked to that status on its job, if any) or an ats_stage_mapping_id (to pick a specific ATS stage, including a custom one). An ATS stage that is not listed cannot be reached until an admin links it in the ATS stage mapping.
send_org_member_email
ChatGPTSend one real email from Ribbon to one member of this organization, with a subject and body you write. Only addresses from list_org_members can be reached; candidates and anyone outside the org cannot. Before calling, show the user the recipient, the subject and the exact body, then obtain explicit approval. Write the body as plain text: it is inserted into a plain Ribbon email shell, so markdown and HTML appear literally. The email says it was sent by you through Ribbon, and replies do not come back to this conversation.
send_outreach
ChatGPTQueue real email, SMS, and/or WhatsApp outreach to candidates already in an open Ribbon role. Before calling, show the user the role, recipient emails and count, every selected channel, the exact message copy, and any reminder schedule, then obtain explicit approval. SMS may first send Ribbon's fixed consent prompt; WhatsApp begins with the approved template required by the provider. Queued new leads advance to contacted and may sync to a linked ATS stage. Queueing does not prove delivery. This operation is not request-idempotent: after a lost or ambiguous response, inspect the role's outreach in Ribbon and never retry automatically.
update_candidate_status
ChatGPTMove one or more candidates to a different stage of a role's Ribbon pipeline. Takes email addresses, not names: if you were given a name, call list_interview_transcripts with candidate_name_contains first to resolve it. All emails must already be in that role's pipeline — the call fails without changing anything if any is missing. This fires the org's candidate-status webhook if one is configured.
update_interview_flow_status
ChatGPTClose a role, so no new interviews can be taken for it. Closing is reversible and deletes nothing: the role keeps its candidates, its interviews, its scoring and its ATS job link, and a recruiter reopens it in Ribbon in one click. What changes is that candidates who have not interviewed yet can no longer start one, and the role stops being offered to candidates applying to the org's other roles. Pass the role's interview_flow_id from list_interview_flows, which also returns each role's status and created_at. Closing a role that is already closed changes nothing and is not an error -- changed tells you whether this call was the one that closed it -- so a sweep over several roles can close them all without checking each one first. closed is the only status this tool can set: it cannot reopen a role, and it can never delete one. A role a recruiter has deleted cannot be closed.
update_interview_scores
ChatGPTAdd, edit or delete the interview scores on a role. Send a score's existing id (from list_interview_scores) to edit it, or omit id to create a new one; the order you send them in becomes their display order. Scores you leave out are untouched — removing one requires naming it in deleted_ids. Adding or changing a score re-scores every completed interview on the role against it, which runs in the background and takes a few minutes; the new result replaces the stored one. Deleting a score is destructive and cannot be undone: it also erases every completed interview's result for that score, so show the user the scores you are about to delete and get their approval first. Creating a score is not idempotent — a score sent without an id is created again on a repeat call, so after a lost or ambiguous response read list_interview_scores back instead of retrying.