Recruit

Recruit action reference

Discover the exact action and granted workspace before running a request. Application permissions, hiring-team roles and record visibility all apply.

An Auth API key acts only in a workspace it is bound to, never does more than its owner's hiring-team role, needs the candidates.read or candidates.write scope for candidate personal data, and is refused the actions a person must take (each action lists the API-key errors it can return).

• Get widget summary: Get the TopoloOne widget summary for this service.
• Get workspace bootstrap: Get the verified user and organization context for this service.
• Get Recruit settings: Read the workspace's candidate privacy notice, data retention period (days a candidate is kept after their latest application) and whether applicants get an automatic acknowledgement email. Recruiters and hiring managers only.
• Update Recruit settings: Change the privacy notice shown on application forms (null restores the default notice), the retention period in days (30 to 3650; applies to applications from now on) or automatic acknowledgement emails. Only the fields sent change. Recruiters only.
• Get the job board: Read the workspace's public job board: its address (slug), title, intro, whether it is published, its public URL (the active custom domain when there is one, see domains.list; otherwise its Recruit address), the iframe embed code for the organization's own website, how many roles are open on it, its appearance settings, what the organization's Brand offers it, and the appearance its pages render now (effectiveAppearance). Only open roles are ever listed publicly.
• Update the job board: Set the job board's slug (its unique public URL /jobs/{slug}), title (the company name candidates see), intro and appearance, live at once; job_board.draft.update edits a draft instead. appearance.source brand (default) follows the organization's published Brand; a field the board sets overrides Brand and null clears it; manual ignores Brand. Appearance holds logos, colour, font, themeMode, header and footer links, the hero (text or image variant, headline, subheadline, cover with alt text and focal point), the optional sections (about, whyJoin, benefits, gallery, hiringProcess; fixed order, each on or off), rolesList, confirmationMessage and seo. Limits are in the input schema. Only fields sent change; a list sent replaces that list. Recruiters only.
• Edit the job board's draft appearance: Change the board's next appearance without changing the live board: the same appearance fields and limits as job_board.update, applied on top of the current draft (or of the live appearance when there is none). Check it with job_board.preview, then make it live with job_board.draft.publish or drop it with job_board.draft.discard. Only the fields sent change. Recruiters only.
• Publish the job board's draft appearance: Make the board's draft appearance live: the public pages show it on their next view and the draft is cleared. Answers 409 board_no_draft when there are no unpublished changes. Publishing the board itself is job_board.publish. Recruiters only.
• Discard the job board's draft appearance: Drop the board's unpublished appearance changes; the live board is unchanged. A board without a draft is returned unchanged. Recruiters only.
• Preview the job board: Create a link, valid for one hour, that shows the board's own pages with its draft appearance (or the live one without a draft), whether or not the board is published. Preview pages are never cached or indexed and do not take applications. A new link replaces the previous one. Needs the board's slug. Recruiters only.
• Upload a job board image: Store an image for the job board (a logo, the hero cover, a gallery picture or the share image) and get its public https url to use in an appearance field. PNG, JPEG or WebP only, checked against the bytes, sent as base64. Images are public once uploaded. Recruiters only.
• Publish the job board: Make the job board public at its publicUrl. Only roles with status open appear on it; closing a role removes it immediately. Requires a slug and title. Applicants are anonymous, so an application never changes an existing candidate: one that uses an existing candidate's email becomes a new candidate flagged duplicateOf them (merge with candidates.merge), and a repeat application to the same role is only noted on the existing application's timeline. The applicant sees the same confirmation either way. Recruiters only.
• Unpublish the job board: Take the job board offline: its public pages answer 404 and no new applications arrive. Roles, candidates and the board settings are kept. Recruiters only.
• Show the job board on a Topolo Web site: Bind the job board to a Topolo Web site, which then renders its roles, role pages and application form natively in its own theme (Web calls this as the signed-in board admin when it places a recruit.board). Only where RECRUIT_CAREERS_DESTINATIONS is on (else 403 destinations_disabled) and only for an origin Recruit can prove belongs to the organization's Web site siteId (else 403 destination_unverified; refused until Web lands). boardId comes from job_board.get; origin is the site's https origin (no path, port, IP address, Topolo host or Recruit custom domain); basePath is "" or a path such as /careers. While bound, publicUrl, canonicals, JobPosting url and role links point to origin + basePath, hosted board and role pages answer 301 there, and the public apply endpoint accepts only that origin. Rebinding the same site updates origin and basePath; another site is refused until unbound. Recruiters only, signed in (not an API key).
• Stop showing the job board on a Topolo Web site: Restore the hosted job board: canonical links and role links point to Recruit again, the redirects stop and the public apply endpoint stops accepting applications from the site. Pass siteId to unbind only from that site (Topolo Web does, so a stale placement never unbinds another site). An already hosted board is returned unchanged. Roles, candidates and settings are untouched. Recruiters only, signed in (not an API key).
• List careers board references: List the workspace's job board as a placeable Connected Apps reference (recruit.board, "Careers board"): id, label (the board title), status (published or unpublished), url (its public address while published, else null) and updatedAt. A workspace has at most one board; a board never saved is not listed. q filters by title, slug or id. Recruiters and hiring managers.
• Get a careers board reference: Read the workspace's job board as a placeable Connected Apps reference (recruit.board): label, status (published or unpublished), url (its public address while published, else null; the Web site address while bound) and updatedAt. Recruiters and hiring managers.
• Get my hiring-team role: Read the caller's hiring-team role in this workspace (recruiter, hiring_manager, interviewer, or null) and the Recruit actions it allows. Workspace owners and organization admins are always recruiters. Hiring managers see only the roles they manage and their candidates; interviewers see only the candidates they are assigned to interview.
• List the hiring team: List the workspace's explicit hiring-team members and their roles. Workspace owners and organization admins act as recruiters without a row here.
• Set a hiring-team member: Add a person (by Topolo user id) to the workspace hiring team or change their role: recruiter (everything), hiring_manager (their own roles and those roles' candidates) or interviewer (only candidates they interview). A recruiter cannot demote themselves. Recruiters only.
• Remove a hiring-team member: Remove a person from the workspace hiring team; they lose Recruit access in this workspace unless they are a workspace owner or organization admin. Interviews and scorecards they already took part in are kept. Recruiters only.
• Get the hiring overview: Counts for the caller's view of the workspace: roles by status, active applications, applications in the last 7 days, active applications by pipeline stage kind, and the eight most recent applications. Hiring managers see only their own roles.
• List the job board's custom domain: List the job board's custom domain (a workspace has at most one) with its status — pending_dns (publish the records), pending_ssl (claimed; waiting for the certificate, edgeStatus, or the apply form's Turnstile widget, turnstileStatus) or active (the board is served at url) — and the DNS guide whose guide.records are the exact records to publish. edgeTarget is the CNAME target in this environment; null means custom domains are unavailable here. Recruiters only.
• Add a custom domain to the job board: Connect a hostname the organization owns (careers.example.com) to the public job board. Returns the DNS guide for the domain's DNS host, in the request's language; guide.records are the records to publish: a CNAME to the jobs edge host and a TXT ownership record; unrelated records (MX, SPF, DKIM) stay untouched. The domain starts as pending_dns and serves nothing until domains.verify succeeds. Apex domains need CNAME flattening, ALIAS or ANAME at the DNS host; otherwise use a subdomain. Reserved hosting-platform hostnames (Topolo platform zones, workers.dev, pages.dev) are refused with hostname_reserved; any other domain the organization owns can be connected. One custom domain per job board. Recruiters only.
• Verify and connect a custom domain: Check the domain's ownership TXT record on the public resolver, then claim the hostname in Topolo Web's hostname registry for this job board. Web routes the hostname to Recruit, creates its Cloudflare for SaaS custom hostname and attaches it to its own Turnstile widget; Recruit holds no Cloudflare credential. Status moves pending_dns → pending_ssl (claimed; certificate or Turnstile widget not ready) → active, which needs edgeStatus active and turnstileStatus attached. Call it again while pending_ssl: it repeats the claim to refresh both. An active domain is returned unchanged. Recruiters only.
• Remove a custom domain: Release the hostname's claim in Topolo Web's hostname registry (Web deletes its edge hostname and Turnstile membership; a claim already gone counts as released), then delete the domain. The job board stays published at its Recruit address. The organization can then remove the DNS records. Recruiters with workspace:delete only.
• List roles: List the workspace's roles (requisitions), open roles first, optionally filtered by status (draft, pending_approval, open, paused, closed). Hiring managers see only roles they manage; interviewers only roles they interview for.
• Get a role: Read one role with its pipeline stages (in order). New applications land in the first stage of kind applied.
• Create a role: Create a draft role with the default pipeline (Applied, Screening, Interview, Offer, Hired, Rejected). Optional: team, location, remotePolicy (onsite, hybrid, remote), employmentType, a salary range (shown on the job board only when set; salaryCurrency is an ISO 4217 code, salaryPeriod defaults to year), description (plain text; blank lines make paragraphs, "- " lines make bullets), up to 20 application questions, hiringManagerUserId (a recruiter or hiring manager on the team) and requiresApproval (a recruiter must approve before it opens). A hiring manager can create roles only for themselves. The slug (public URL segment) is generated from the title when omitted. The role is not public until roles.open.
• Update a role: Change a role's fields; only the fields sent change and each save is a new version (roles.versions.list). Changing an open role changes the public job board immediately. Only a recruiter can reassign the hiring manager.
• Open a role: Open a draft, paused or closed role so it appears on the published job board and accepts applications. A role that requires approval and has not been approved moves to pending_approval instead (approvalRequired true) until a recruiter calls roles.approve.
• Approve a role: Approve a role waiting for approval (pending_approval, or a draft that requires approval) and open it. Recruiters only.
• Pause a role: Pause an open role: it leaves the job board and stops accepting applications; candidates already in its pipeline are untouched.
• Close a role: Close a role (filled or cancelled). It leaves the job board immediately; candidates and history are kept.
• List role versions: List every saved version of a role, newest first: who changed it, what kind of change (created, edited, opened, submitted_for_approval, approved, paused, closed, reopened) and a snapshot of its fields at that version.
• List candidates: List the workspace's candidates, newest first (default 100, at most 200), each with their applications (id, roleId, stageId, status). Filter by q (name contains, or an exact email), roleId, stageId, tag, or status (active by default; archived). An email query also returns job-board records flagged as possible duplicates of that candidate (duplicateOf set). Hiring managers see only candidates on their roles; interviewers only candidates they interview.
• Import candidates from CSV: Import sourced or referred candidates from CSV text (header row required; columns email plus first_name and last_name or a single name column; optional phone, location, profile_url/linkedin, tags separated by ";" and source_detail). Up to 2000 rows. Always run mode preview first: it changes nothing and reports each row's outcome (create, add_application, existing, duplicate_in_file) and invalid rows by line. mode commit then applies the same plan. Candidates are deduplicated by email, so re-running a commit is idempotent. With roleId every new or existing candidate is added to that role's pipeline once. Recruiters only.
• Get a candidate: Read one candidate's profile: contact details, source, tags, consent and retention date, their applications (with answers and cover letter), documents (metadata; fetch content with candidates.documents.get) and activity timeline, newest first. Only applications on roles the caller may see are included. candidate.duplicateOf is set on a job-board record that used this existing candidate's email; possibleDuplicates lists such records pointing at this candidate (id, name, createdAt) for a recruiter to compare and merge.
• Add a candidate: Add a candidate by hand with source attribution (manual by default; sourced, referral or agency, with sourceDetail such as the referrer). Email is unique per workspace. With roleId the candidate also lands in that role's pipeline at its Applied stage, and is emailed that stage's steps from other apps (steps reports it). Hiring managers must give one of their own roles.
• Update a candidate: Change a candidate's name, phone, location, profile URL, tags or source detail. Only the fields sent change; email cannot change (it is the candidate's identity in the workspace).
• Archive a candidate: Archive a candidate: they leave active lists but their record, applications and documents are kept until retention or erasure. Adding them to a role again (applications.create, or candidates.import with roleId) reactivates them; a job-board application with their email never does, it becomes a separate record flagged duplicateOf them. Recruiters only.
• Merge a possible duplicate: Merge a job-board record flagged as a possible duplicate (candidate.duplicateOf set) into the existing candidate whose email it used. The public job board never changes an existing candidate, because anyone can type any email; this recruiter decision is the only way the two become one. Compare the two first (names, CV, answers) and merge only when they are the same person; otherwise keep the record separate or erase it (candidates.erase). Everything on the flagged record (applications, history, documents, notes, emails, interviews, scorecards, decisions, offers, activity) moves to the existing candidate, whose name and contact details are kept; it takes the later retention date and consent, and becomes active again if the flagged record was active. The flagged record is then deleted. Recruiters only.
• List candidate documents: List a candidate's documents (CVs, cover letters, other files): filename, type, size and SHA-256. Use candidates.documents.get for the content.
• Upload a candidate document: Attach a CV, cover letter or other file to a candidate (optionally to one application). Send the file as base64 in contentBase64. Allowed: PDF, Word (.docx, .doc), OpenDocument (.odt), RTF and plain text, up to 10 MB; the bytes must match the type (the declared contentType is not trusted).
• Get a candidate document: Read one candidate document with its content as base64 (contentBase64). Interviewers can read documents only for candidates they are assigned to.
• Add a candidate to a role: Put an existing candidate into a role's pipeline at its Applied stage. A candidate can apply to each role once. The candidate must be visible to the caller and the role managed by them and not closed. When that stage has steps from other apps the candidate is emailed their personal links; steps reports it.
• Get candidate email event delivery: Event delivery is the organization's Notify webhook subscriptions for nexus.email.replied, nexus.email.bounced.hard and nexus.email.complained, which thread candidate replies onto the candidate's email log and timeline and record bounces and spam complaints. It is per organization (shared by its workspaces). Reads whether each event type is connected.
• Connect candidate email event delivery: Event delivery is the organization's Notify webhook subscriptions for nexus.email.replied, nexus.email.bounced.hard and nexus.email.complained, which thread candidate replies onto the candidate's email log and timeline and record bounces and spam complaints. It is per organization (shared by its workspaces). Creates the missing subscriptions with the caller's own credential (Notify allows only a person with webhooks:manage) and a signing secret Recruit derives and never stores. All or nothing: a failure removes what this call created. Recruiters only.
• Rotate the event delivery secret: Event delivery is the organization's Notify webhook subscriptions for nexus.email.replied, nexus.email.bounced.hard and nexus.email.complained, which thread candidate replies onto the candidate's email log and timeline and record bounces and spam complaints. It is per organization (shared by its workspaces). Replaces the signing secret of every active subscription (new version); on a failure the previous secret is restored everywhere. Recruiters only.
• Disconnect candidate email event delivery: Event delivery is the organization's Notify webhook subscriptions for nexus.email.replied, nexus.email.bounced.hard and nexus.email.complained, which thread candidate replies onto the candidate's email log and timeline and record bounces and spam complaints. It is per organization (shared by its workspaces). Deletes the organization's subscriptions; replies and bounces are no longer recorded. Recruiters only.
• Edit a role's pipeline stages: Replace a role's ordered pipeline stages (1–20). Keep a stage by sending its id; omit id to add one; leave one out to remove it (only when no application is in it). Kinds: applied (where new applications land), screening, interview, offer, hired, rejected, custom; applied, offer, hired and rejected at most once each. Each stage may carry scorecard criteria (id, label) that interviewers rate.
• List applications (pipeline board): List applications, newest activity first (default 200). With roleId this is the role's pipeline board: it also returns the role, its stages in order and counts of applications per stage (all statuses), which always add up to the role's applications. Without roleId it lists across every role the caller can see. Filter by stageId or status (active, rejected, hired, withdrawn). Interviewers see only candidates they interview.
• Get an application: Read one application with its candidate (name, email), role, the role's stages, its complete, append-only stage history and the steps from other apps it has been sent (each with the candidate's link while waiting, and what the form or survey reported once done).
• Move an application to a stage: Move an application to another stage of its role, with an optional reason. Moving to the hired stage marks it hired, to the rejected stage marks it rejected, any other stage makes it active again. Every move appends to the stage history and the candidate timeline. When the stage has steps from other apps (roles.steps.list) the candidate is emailed their personal links to those not sent before; steps reports it, and the move stands whatever happens to that email.
• Reject an application: Reject an application with a reason: it moves to the role's rejected stage (or is marked rejected when the role has none). With sendEmail true the candidate gets the rejection email (templateId, else the workspace's rejection template, else Recruit's default) through Nexus. The rejection stands even if the email cannot be sent; email reports what happened.
• Record a withdrawal: Record that the candidate withdrew their application. It stays on the role's board with status withdrawn and can no longer be moved.
• List candidate notes: List the notes on a candidate, newest first, with the hiring-team members each one mentions. Notes about an application on a role the caller cannot see are left out.
• Add a note to a candidate: Add a note to a candidate, optionally about one of their applications, mentioning hiring-team members by user id. Notes are never edited or deleted (they are part of the hiring record) until the candidate's data is erased.
• List email templates: List the workspace's candidate email templates (active by default), optionally by kind: acknowledgement (sent automatically when a candidate applies), interview_invitation, rejection, offer, custom. A kind with no template uses Recruit's default. Merge fields: {{candidate.first_name}}, {{candidate.last_name}}, {{candidate.full_name}}, {{role.title}} (the application's role), {{company.name}} (the job board title), {{sender.name}} (the caller's name), {{interview.title}}, {{interview.when}}, {{interview.location}} (from values), and {{steps.links}} (the application's waiting stage steps, each title over the candidate's personal link).
• Create an email template: Create a candidate email template. The newest active template of a kind is the one Recruit uses for that kind. Merge fields: {{candidate.first_name}}, {{candidate.last_name}}, {{candidate.full_name}}, {{role.title}} (the application's role), {{company.name}} (the job board title), {{sender.name}} (the caller's name), {{interview.title}}, {{interview.when}}, {{interview.location}} (from values), and {{steps.links}} (the application's waiting stage steps, each title over the candidate's personal link).
• Update an email template: Change a template's name, subject or body. Merge fields: {{candidate.first_name}}, {{candidate.last_name}}, {{candidate.full_name}}, {{role.title}} (the application's role), {{company.name}} (the job board title), {{sender.name}} (the caller's name), {{interview.title}}, {{interview.when}}, {{interview.location}} (from values), and {{steps.links}} (the application's waiting stage steps, each title over the candidate's personal link).
• Archive an email template: Archive a template so it is no longer used; the next newest active template of its kind, or Recruit's default, takes over.
• List a candidate's emails: List every email sent to (and received from) a candidate, newest first, with its status: queued (Notify accepted it; the outcome is not known yet), sent, skipped (the address is suppressed), failed (with error; retry it with candidates.emails.retry) or received. Recruit reads each queued email's outcome from Notify within minutes. Emails recorded as sent before queued existed stay sent.
• Email a candidate: Send a transactional email to a candidate through Nexus, from a template (templateId) or with your own subject and body. It is sent from the organization's own sender identity when one is configured, otherwise from Recruit's shared sender on the organization's behalf. Without applicationId the candidate's most recent application gives {{role.title}}. Nothing is sent while any merge field is unresolved. Merge fields: {{candidate.first_name}}, {{candidate.last_name}}, {{candidate.full_name}}, {{role.title}} (the application's role), {{company.name}} (the job board title), {{sender.name}} (the caller's name), {{interview.title}}, {{interview.when}}, {{interview.location}} (from values), and {{steps.links}} (the application's waiting stage steps, each title over the candidate's personal link).
• Retry a failed candidate email: Send a failed outbound email again: the same recipient, subject and body, with a new idempotency key so Notify sends it afresh. The email row becomes queued again (its retry count goes up) and its outcome is read from Notify like any send. Only an email with status failed can be retried. Recruiters and hiring managers who can see the candidate.
• List apps offering stage steps: The provider apps whose forms or surveys Recruit can place in a stage step, with whether each is connected to Recruit, whether a connection request is waiting, and the types each offers. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them. An app that has not declared the type yet is absent.
• Connect an app for stage steps: Connect a provider app (app_topolo_forms or app_topolo_survey) to Recruit for the organization. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them. An organization admin's call activates the connection; anyone else's becomes a request an admin approves (outcome requested).
• List provider workspaces for stage steps: The provider app's workspaces the caller can use from this Recruit workspace, with whether each is linked to it (only linked ones can be searched) and whether a link request is waiting. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them.
• Link a provider workspace: Link a provider workspace to this Recruit workspace so its forms or surveys can be placed in stage steps. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them. An admin of both workspaces links at once; anyone else's call becomes a request (outcome requested).
• Search forms or surveys for a stage step: Search a linked provider workspace for forms (type forms.form, app_topolo_forms) or surveys (type survey.survey, app_topolo_survey) by title; pass nextCursor back as cursor for more. Each item's reference is what roles.steps.add takes. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them.
• List a role's stage steps: A stage step is a Topolo Forms form or Topolo Survey survey that a pipeline stage sends each candidate who reaches it (moved there, added to the role, or applying on the job board into the entry stage): each candidate gets their own link carrying a token in the providers' reserved topolo_ctx parameter (no hidden field needed), and the submission or response (forms.submission.created, survey.response.created through Recruit's connection) is recorded on the candidate (applications.get steps[]). Lists the role's steps by stage with each placement's current status from Developers (ready, changed, unavailable, removed, access_removed); a status Developers cannot be asked for right now (or for an API key) is the last one Recruit saw.
• Add a step from another app to a stage: Adds a Topolo Forms form or Topolo Survey survey (reference from references.search) to one of the role's stages as a stage step, at most five per stage. Each candidate who reaches the stage next (moved there, added to the role, or applying on the job board into the entry stage) gets their own link with a token in the providers' reserved topolo_ctx parameter, and the submission or response is recorded on the candidate (applications.get steps[]); candidates already in the stage are not sent it. Recruit places it in Developers (consumer kind recruit.stage.step) and reads the respondent link through the provider's reference get action. No hidden field is needed. It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them.
• Check a role's stage steps again: A stage step is a Topolo Forms form or Topolo Survey survey that a pipeline stage sends each candidate who reaches it (moved there, added to the role, or applying on the job board into the entry stage): each candidate gets their own link carrying a token in the providers' reserved topolo_ctx parameter (no hidden field needed), and the submission or response (forms.submission.created, survey.response.created through Recruit's connection) is recorded on the candidate (applications.get steps[]). Re-checks every step with Developers and its provider (placements.refresh): its status, title and, while the resource is reachable, its respondent link (null once unpublished, which stops it being sent). It passes to Topolo Developers as the signed-in person: Developers checks the connection between Recruit and the provider app, the person's access to both workspaces and the link between them.
• Remove a step from a stage: A stage step is a Topolo Forms form or Topolo Survey survey that a pipeline stage sends each candidate who reaches it (moved there, added to the role, or applying on the job board into the entry stage): each candidate gets their own link carrying a token in the providers' reserved topolo_ctx parameter (no hidden field needed), and the submission or response (forms.submission.created, survey.response.created through Recruit's connection) is recorded on the candidate (applications.get steps[]). Removes a step and deletes its Developers placement. Candidates already sent it keep their links, and their results are still recorded.
• List interviews: List interviews by start time, optionally for one application, by status, or only the caller's own (mine=true). Interviewers always see only interviews they are on; hiring managers only those for roles they manage. Each interview carries candidateName, roleTitle and interviewers[] with display names, so no further reads are needed to show it.
• Get an interview: Read one interview with the candidate's name, the role title, the interviewers' display names and the scorecard criteria the interview stage defines.
• Schedule an interview: Schedule an interview for an application at its current stage: title, start and end (ISO 8601 with offset), optional time zone (IANA, used to word the invitation), location or https meeting URL, and 1–10 interviewers from the hiring team. With sendInvitation the candidate gets the interview invitation email (templateId, else the workspace's, else Recruit's default) with interview.title, interview.when and interview.location filled in. Calendar, Sign and People are optional: times are entered here, and a signature or People record reference is stored when the team has one.
• Reschedule or update an interview: Change a scheduled interview's title, time, time zone, location, meeting URL or interviewers (the list replaces the current one). No email is sent; tell the candidate with candidates.emails.send.
• Cancel an interview: Cancel a scheduled interview with an optional reason. Draft scorecards for it can no longer be saved.
• Get my scorecard: Read the caller's own scorecard for an interview they are on (null before they save one) and the criteria to rate. A scorecard is private to its author until submitted.
• Save my scorecard draft: Save the caller's draft scorecard for an interview they are on: ratings 1 (poor) to 4 (excellent) for the stage's criteria with optional notes per criterion, a recommendation (strong_no, no, yes, strong_yes) and overall notes. Only the fields sent change. A submitted scorecard cannot change.
• Submit my scorecard: Submit the caller's scorecard (a recommendation is required). It becomes immutable and visible to the hiring team; when every interviewer has submitted, the interview is completed. Interviewers see colleagues' feedback only after submitting their own.
• List an application's scorecards: List the scorecards for an application. Recruiters and hiring managers see every submitted scorecard; an interviewer on the application sees only their own until they have submitted it, then everyone's submitted ones. Drafts are visible only to their author. hidden counts what the caller cannot see; locked is true when colleagues' submitted scorecards are withheld until the caller submits their own, and drafts counts colleagues' unsubmitted drafts.
• List hiring decisions: List the hiring decisions recorded for an application, oldest first: advance, hold, reject or hire, with the rationale, who decided and when.
• Record a hiring decision: Record a hiring decision with its rationale on an application. Decisions are append-only and auditable; recording one does not move the application (use applications.move, applications.reject or offers.*).
• List offers: List offers, most recently changed first, optionally for one application or by status, for roles the caller can see.
• Get an offer: Read one offer with its complete event history (created, edited, sent, accepted, declined, withdrawn).
• Draft an offer: Draft an offer for an active application: salary (defaults from the role's range), currency, period, start date (YYYY-MM-DD) and terms. One offer can be in progress per application. Calendar, Sign and People are optional: times are entered here, and a signature or People record reference is stored when the team has one.
• Edit a draft offer: Change a draft offer's salary, currency, period, start date or terms. Sent offers cannot change: withdraw and draft again.
• Send an offer: Mark a draft offer as sent, optionally with the reference of a signature request made elsewhere (signatureRef), and with sendEmail the candidate gets the offer email (templateId, else the workspace's, else Recruit's default). Calendar, Sign and People are optional: times are entered here, and a signature or People record reference is stored when the team has one.
• Record the candidate's answer: Record that the candidate accepted or declined a sent offer, with an optional note and People record reference. Accepting is a hire: the application moves to the role's hired stage (or is marked hired). Calendar, Sign and People are optional: times are entered here, and a signature or People record reference is stored when the team has one.
• Withdraw an offer: Withdraw a draft or sent offer with a reason.
• Get the hiring funnel: Hiring analytics for the caller's roles (or one roleId), optionally for applications since a date: applications per role, how many applications ever reached each stage kind (applied, screening, interview, offer, hired) with conversion from applied, hires and the median days from application to hire.
• Export a candidate's data: Export everything Recruit holds about one candidate (a subject access request): the candidate record, applications, stage history, notes, activity, documents with their content as base64, interviews, scorecards, decisions, offers and their events, and emails. Recruiters only.
• Erase a candidate: Permanently erase a candidate (a deletion request): their documents are deleted from storage, then every record about them (applications, history, notes, activity, interviews, scorecards, decisions, offers, emails) in one batch. An erasure record without personal data (opaque id, who, why, counts) is kept for accountability. Recruiters with workspace:delete only; confirm must be true.
• Get candidate data retention: The workspace's retention period (days after a candidate's latest application), how many candidates are now past it with no active application (Recruit erases them in its daily pass), and the 20 most recent erasures (request or retention) without personal data. Recruiters only.

Evidence

Actual dispatcher and migration-created SQLite or Worker handlers; Auth/workspace identity, object storage, mail and Notify dependencies are simulated. These synthetic fixtures establish no live authorization or delivery.

Documentation history

• 2026-10-18: Extended this existing action index from 73 to 96 entries while preserving the original guide identities. Added the 23 reviewed action guides and their paired agent guidance; source and local fixture provenance do not establish production action execution.