add_candidate_note
ChatGPTAdds a private team note (Markdown) to a candidate, optionally attached to a session or a journey. Notes are never shown to the candidate or a client. Each teammate in mentionUserIds (ids from list_teammates) is emailed about the note and notified in the app.
analyze_sheet_import
ChatGPTReads one tab of a connected sheet's spreadsheet and returns its column headings and a suggested mapping (email, first and last name or one full-name column, position, resume link) with the AI's confidence. Show the mapping to the user before import_sheet_rows. Each call counts as one bulk-list parse: the first 50 a month are free, then 1 credit per 10, so call it once per tab, never in a loop.
approve_ai_grade
ChatGPTAccept the AI grade on a submission, so its AI score becomes the submission's final score (a take-home's is capped by its ownership verdict). Updates the session composite score; if an automation rule is set on the stage, a completed composite may advance or reject the candidate. The submission id comes from get_session_results.
approve_ai_grades
ChatGPTApprove every finished AI grade of several candidates' tests at once (grades only; the PASSED or FAILED decision stays separate, see submit_final_decisions). A sitting flagged by the integrity check, a sitting still grading and a sitting with nothing to approve are skipped with the reason. Updates each session's composite score; if an automation rule is set on the stage, a completed composite may advance or reject the candidate, which can email them.
archive_assessment
ChatGPTArchives an assessment so it is no longer offered for new invites. Existing candidate sessions and results are kept. Deleting an assessment is not available to assistants because it also erases every candidate result on it; archiving is the way to retire one.
archive_candidates
ChatGPTArchives candidates: by positionCandidateIds (the journey and all its sessions) or by sessionIds (a session with a journey archives the whole journey). Archived candidates are hidden everywhere, their invite links stop working, and they are permanently deleted after 30 days unless restored with restore_candidates. This is also the first step of deleting someone (delete_archived_candidates removes archived ones at once), so tell the user about the 30-day purge. Emails nobody. It is also how to cancel an invite sent to the wrong person: the link stops working, though the email already sent cannot be recalled. Returns how many candidates changed.
archive_client
ChatGPTArchives an agency client, hiding it from lists; its positions, candidates and shortlists are kept. This is the normal way to retire a client. Reversible with restore_client.
capture_challenge_sample
ChatGPTSaves one graded answer from a candidate session of the company as the anonymous STRONG or WEAK sample report of that question, which preview links show next to it. The report carries the scores and the AI's written account, never the candidate's name or contact details. Replaces the question's earlier sample of the same label. The answer must have a finished AI grade; pick a sitting that reads as a fair example.
change_teammate_role
ChatGPTSwitches a teammate between INTERVIEWER and COMPANY (admin). Nobody can change their own role, and the last active admin cannot be demoted. The teammate is signed out everywhere so the new role applies at their next sign-in.
clear_notifications
ChatGPTDeletes the signed-in user's notifications, all of them or the given ids. Confirm with the user first. Returns how many were deleted; another user's id is simply not matched. Ids come from list_my_notifications.
close_apply_link
ChatGPTStops an apply link: the public form answers not found and nobody can apply through it. Applications already in stay on the Resume screening page. create_apply_link on the same position reopens it with a new URL, keeping its applications.
create_apply_link
ChatGPTCreates the public application form for an open position and returns its URL (list_apply_links shows it again; give it to the user to post on the job ad). Anyone holding the link can apply: a candidate enters their name, email and an optional LinkedIn link, attaches a resume and consents; the resume is screened like an upload and appears on the Resume screening page marked Applied, with the applicant's own identity. Each application sends the applicant a confirmation email. One link per position; a position whose link is closed gets a fresh URL. The public description defaults to the position's description. The form always asks for first name, last name, email, a resume and consent (LinkedIn optional); the company may add up to 8 questions of its own (short text, long text, yes/no, a pick list), each optionally required, and "How hiring works" steps. The page also shows the role facts set on the position (update_position facts: location, work mode, employment type, experience, salary when shown, skills). Emails nobody at creation.
create_assessment
ChatGPTCreates an assessment as a DRAFT from challenge ids (from list_challenges, list_assessment_templates or recommend_assessment). A draft cannot be sent to candidates until publish_assessment. Emails nobody and spends nothing. It is not linked to any position: to make it a position's test, set it as the position's default assessment with update_position (check get_position first, the position may already have a test with candidates on it).
create_candidate_tag
ChatGPTCreates a company-wide candidate tag. Apply it with set_candidate_tags. Tags are team-only, never shown to candidates or clients.
create_challenge
ChatGPTCreates a challenge owned by the company. Coding challenges need functionName, inputTypes, outputType, languageTemplates and testCases (each input line is one function argument); MCQ needs mcqQuestions; agentic and take-home challenges use their own fields. Check get_challenge_for_edit on a similar library challenge for the shape. Emails nobody.
create_client
ChatGPTAdds a client company to an agency account (a label; clients have no login). Searches are confidential by default: candidates see only the agency. Set revealToCandidates true only when the user explicitly says the client may be named to candidates.
create_position
ChatGPTCreates a job opening. The description is Markdown (bold, italic, headings, - and 1. lists); screening notes guide AI resume screening and the assessment recommendation. Set defaultAssessmentId so invites and the position's assessment stage use that test. Emails nobody and spends nothing.
create_preview_link
ChatGPTCreates a preview link that shows one person (a lead, a hiring manager) up to five questions exactly as a candidate sees them, plus anonymous sample reports, and returns the URL (list_preview_links shows it again; give it to the user to send). Nothing on the page is timed, scored, recorded or billed, and it is not a candidate invite. The label is who it is for, as the page says it ("Michael at Seekr"): a first name and a company, never an email. The page shows no person's name and not the company that made it. Questions are library challenges or the company's own, from list_challenges. Links expire after 7 days by default (1 to 30 days) and can be revoked.
create_shortlist_share
ChatGPTPublishes a shortlist of completed, fully graded candidates to one agency client as a public link the client opens without a login, and returns that URL once (it cannot be retrieved later; give it to the user to send). Anyone holding the link can see the shared candidates, and it now sits in this conversation; revoke_shortlist_share turns it off. The client sees skill grades and the resume fit; candidate email (showContact) and integrity signals (showIntegrity) are shown only if switched on, both off by default. Confirm candidates and switches with the user first.
delete_archived_candidates
ChatGPTPermanently deletes ARCHIVED candidates now (sessions, submissions, results), instead of waiting for the 30-day purge. Cannot be undone; live (not archived) candidates in the list are skipped without an error, so archive them first with archive_candidates. Company admins only. Returns the number of test sessions deleted (a candidate with two tests at a position counts 2; a journey with no test counts 0), not the number of ids you sent; a live id deletes nothing, so tell the user which ones were not archived.
delete_candidate_note
ChatGPTDeletes a candidate note. Only its author (or a company admin) may delete it. The id comes from list_candidate_notes.
delete_candidate_tag
ChatGPTDeletes a candidate tag and removes it from every candidate that carries it. The id comes from list_candidate_tags.
delete_challenge
ChatGPTPermanently deletes one of the company's own challenges with its test cases. Library challenges cannot be deleted. Confirm with the user first.
delete_client
ChatGPTPermanently deletes an agency client. Refused while any position, candidate session or shortlist references it; use archive_client instead in that case.
delete_position
ChatGPTPermanently deletes a position with its hiring process and every candidate's stage history at it. Candidate sessions and test results are kept. Closing it with update_position (status CLOSED) is usually what the user wants; confirm before deleting.
delete_resume
ChatGPTPermanently delete one screened resume, its file and its analysis. Candidates already invited from it keep their sessions. Cannot be undone.
delete_resume_batch
ChatGPTPermanently delete an upload batch and every resume in it, with their files and analyses. Cannot be undone.
delete_resumes_for_position
ChatGPTPermanently delete every resume screened for a position; returns how many were deleted. The position itself and any invited candidates stay. Cannot be undone.
delete_sheet_control
ChatGPTDisconnects one sheet: Hireinator stops reading and updating it. The customer's spreadsheet and its data are left as they are. Reconnecting needs the browser; confirm with the user first.
disconnect_google_sheets
ChatGPTForgets the company's connected Google account and pauses every sheet that used it. Reconnecting needs the browser sign-in; confirm with the user first.
disconnect_workday
ChatGPTDisconnects the company's Workday tenant: new Workday assessment requests stop arriving and results stop being written back. Reconnecting needs the credentials again in the browser; confirm with the user first.
edit_candidate_note
ChatGPTReplaces the body of a candidate note. Only its author (or a company admin) may edit it; nobody is emailed. The id comes from list_candidate_notes.
find_candidates
ChatGPTFinds candidates of the company by name or email (ONE person per call: for several people call it once per name; any part, e.g. "priya", "nair priya" or "@acme.com"), archived ones included, and returns each person with every test session (status, score, decision, archivedAt) and every journey (position, stage, status). People with a live (not archived) session or journey come first. sameNameCount is how many OTHER people share the exact name, archived ones included; archived look-alikes rarely need a question. When the conversation already says which one (the position being discussed, the test), use that and say which you picked; otherwise ask, naming their emails and positions. An empty list means nobody of that name has been invited; say so plainly.
generate_interview_questions
ChatGPTDrafts up to 8 AI interview questions from a position's job description, each with a secret rubric, an optional clarification, an answer limit and whether a follow-up is asked. Creates nothing: show the draft to the user, then pass it to create_challenge with challengeType INTERVIEW once they have reviewed every rubric. Costs an AI call, never credits. Emails nobody.
get_ai_check
ChatGPTGet one AI grading check: status (PENDING, RUNNING, COMPLETED, FAILED), AI score, sub-scores, reasoning, feedback and suggestions. Use it to follow a check started with run_ai_grading. Cheating risk, indicators and the take-home ownership verdict are signals for a person to review, not a verdict.
get_assessment
ChatGPTReturns one assessment with its description, duration, status and its challenges in order (type, time limit, take-home effort). Use get_challenge for a challenge's full content.
get_assessment_credit_cost
ChatGPTHow many credits one candidate starting this assessment will spend (0 for an MCQ-only test), with the breakdown by question type. Inviting is free; these credits are used when the candidate starts, and it already covers AI grading and the cheating check. Use it before a large invite to check the balance covers it (credits x candidates who start).
get_assessment_stats
ChatGPTReturns the funnel and outcome of each assessment (test) of the company, or of one: invited, not started, in progress, completed, expired (started but ran out of time), completion rate (completed out of those who finished or ran out), graded, average composite score, PASSED and FAILED decisions, pass rate (PASSED out of decided) and average time taken. Use it for "which test has the worst pass rate" or "how is this test doing". Rates are null until there is something to divide; small counts make a rate unreliable, so say how many candidates it rests on. Archived candidates are left out. For one question's difficulty use get_challenge_analytics.
get_candidate_scorecard
ChatGPTGet a session's scorecard: decision, composite score and letter grade, averaged sub-scores, and a per-submission breakdown (type, grade status, final and AI score, sub-scores, reasoning). A compact summary; use get_session_results for test results and details. sessionCheatingRisk is the session's integrity signal (the session cheating check, null until one has run); avgCheatingRisk only averages the per-question AI risk. Both are signals for a person to review, not a verdict.
get_candidate_session
ChatGPTReturns one candidate session: status, timing, composite score, the review decision, position, client, journey stage, the per-question submissions (challenge, auto score, AI score, AI grade status, final score), the cheating check and the session behavioral counts. MCQ submissions read aiGradeStatus AUTO_GRADED (scored on submit, no approval needed). The id comes from list_candidate_sessions or a journey's stageSession. Use the results tools for full test output and AI reasoning.
get_challenge
ChatGPTReturns one challenge as a recruiter reviews it: the task text, type, difficulty, time limit, the languages offered with their starter code, the public test cases in full, how many hidden test cases there are (their inputs, never their expected outputs), the MCQ questions and options (without which option is correct), the agentic or take-home setup, and an AI interview's questions as the candidate meets them (never the rubric or the resume hints). The answer key is left out on purpose so it never sits in a conversation; use get_challenge_for_edit only when the user is editing the challenge.
get_challenge_analytics
ChatGPTReturns how one challenge performs across candidates: attempts, drop-offs, completion rate, average auto score, pass rate at a threshold (default 70), average time and the score distribution in five 20-point buckets. Use it to judge whether a question is too hard or too easy.
get_challenge_for_edit
ChatGPTReturns one challenge in full as the team edits it, INCLUDING what candidates must never see: every test case with its expected output, the reference solutions, the MCQ answer key and explanations, the agentic planted defect, the take-home rubric and debrief probes, an AI interview's rubrics and resume hints. Use it only to build the input of update_challenge (or to copy a library challenge's shape for create_challenge); for anything else use get_challenge. Do not repeat answers in the conversation unless the user asks for them.
get_challenge_translation
ChatGPTReturns the cached machine translation of a challenge's candidate-facing text into a language, with needsReview and stale flags; null when none exists yet. Candidates who pick that language see it; grading always reads the English.
get_client
ChatGPTReturns one agency client in full, including the agency's internal notes and whether candidates are told the client's name (revealToCandidates).
get_company_hiring_template
ChatGPTReturns the company's template hiring process: the ordered stages every new position copies, and whether a PASSED decision moves a candidate to the next stage (passAdvancesStage). Stage kinds: SCREEN (must be first, exactly one), ASSESSMENT (a test; assessmentId omitted means the position's default assessment, at most one stage may rely on that, and an assessment may appear only once), CLIENT_REVIEW (agencies: submitted to the client), INTERVIEW, OFFER, HIRED (must be last).
get_credit_balance
ChatGPTReturns the company's credit balance. When it runs out, invited candidates cannot start their test (they see a neutral "unavailable" message), so check it before inviting many people. Hireinator counts usage in credits: one credit is one candidate on a standard test (up to 3 AI-graded coding questions), each agentic round adds 1 credit and each take-home adds 2; MCQ-only tests use none. Credits are used when a candidate starts a test.
get_dashboard_stats
ChatGPTReturns this month's headline numbers for the company: tests completed, invites expired (links that lapsed unused plus tests that ran out of time; list_needs_attention names the recent ones), median hours from completion to decision, and credits used (candidate starts, screening, parsing, integrations).
get_grading_batch
ChatGPTShows how far one bulk AI grading run has got: total, done, running, queued and failed checks, and per session its grading state and progress over the AI-graded rounds. The batch id comes from grade_candidates_with_ai. A batch is finished when queued and running are both 0; a failed check is retried by grading that candidate again.
get_help
ChatGPTHireinator's own product help: how things work, how to set things up in the app, why something happens, and what to do when something goes wrong. Call it before answering a how, why or can-it question from memory, or before saying something is not possible. Without a topic it lists the topics. It explains the product in general; for this company's own numbers and state use the data tools it names.
get_integrations_status
ChatGPTReturns the state of the company's integrations: whether a Google account is connected for Sheets (and which), the Workday connection's health, recent issues and status Reference IDs (never credentials), and the webhook endpoints with their health (never signing secrets). Connecting anything new happens in the browser, by a company admin, on the integrations page: the path /company/integrations on the same host as the usage link in the server instructions. The step-by-step guides are public on that host too: /developers/workday, /developers/google-sheets, /developers/webhooks, /developers/zapier and /developers/n8n. Nothing can be connected from here.
get_journey
ChatGPTReturns one candidate's journey at a position: current stage, status, sub-state, tags, note count, resume fit score, client feedback and the result of every assessment stage. The id (positionCandidateId) comes from get_position_pipeline or list_candidate_sessions (journey.id). subState is where the candidate is inside the current stage: at an ASSESSMENT stage NONE (no test sent for it yet), INVITED (link sent, not started; inviteExpired true means the link is dead and only resend_candidate_invite helps), IN_PROGRESS, EXPIRED (started, but the time ran out before they submitted), TO_REVIEW (test finished, some answer not graded yet or its AI grade waiting for approval), REVIEWED (every grade decided; stageSession.finalRecommendation says PASSED, FAILED or UNDECIDED); otherResults lists tests the candidate took for this position that no stage names; at SCREEN NOT_SCREENED or SCREENED (a resume fit score exists); at CLIENT_REVIEW the client's answer (AWAITING_CLIENT, CLIENT_INTERESTED, CLIENT_NOT_NOW, CLIENT_PASSED); NONE at every other stage.
get_journey_history
ChatGPTReturns the history of a candidate's journey at a position: every stage move and status change with who made it (null = automation), the reason and when, including stage emails sent. The positionCandidateId comes from get_position_pipeline or list_candidate_sessions (journey.id).
get_my_company
ChatGPTReturns the caller's company: its id (needed by update_company_settings and remove_teammate), name, website, account type (COMPANY hires for itself, AGENCY hires for clients), company language, default candidate invite language (null means the inviting person's language), booking link and candidate email branding (brand colour, sender name, Reply-To).
get_my_profile
ChatGPTReturns the signed-in user's own profile: name, email, role (COMPANY is a company admin, INTERVIEWER a team member), language and personal booking link (the {bookingLink} in candidate stage emails, ahead of the company's link). Use it to know who you act as and what they may do.
get_pipeline_summary
ChatGPTReturns stage counts for every open position of the company: active, to review and rejected totals plus the count per stage. toReviewCount is the active candidates with a finished test whose grades are not all decided (AI grading not yet run or waiting for approval); finished tests with every grade decided but no PASSED/FAILED yet are not in it (list_needs_attention has both). Use it for an overview of where hiring stands, then get_position_pipeline for one position's candidates. Agency accounts can filter by clientId.
get_position
ChatGPTReturns one position in full (Markdown description, screening notes, default assessment, client, Workday requisition id) together with its hiring process stages and how many active candidates sit in each. The first read gives the position its own copy of the company template.
get_position_pipeline
ChatGPTReturns one position's hiring board: its stages (ids, kinds, linked assessment) and every candidate journey with current stage, status, sub-state, days in stage, tags and the current stage's session score. Journey ids are the positionCandidateId and stage ids the stageId that move_candidate_to_stage and the other stage tools take. The positionId comes from the positions tools or get_pipeline_summary. subState is where the candidate is inside the current stage: at an ASSESSMENT stage NONE (no test sent for it yet), INVITED (link sent, not started; inviteExpired true means the link is dead and only resend_candidate_invite helps), IN_PROGRESS, EXPIRED (started, but the time ran out before they submitted), TO_REVIEW (test finished, some answer not graded yet or its AI grade waiting for approval), REVIEWED (every grade decided; stageSession.finalRecommendation says PASSED, FAILED or UNDECIDED); otherResults lists tests the candidate took for this position that no stage names; at SCREEN NOT_SCREENED or SCREENED (a resume fit score exists); at CLIENT_REVIEW the client's answer (AWAITING_CLIENT, CLIENT_INTERESTED, CLIENT_NOT_NOW, CLIENT_PASSED); NONE at every other stage.
get_resume_analysis
ChatGPTGet one resume's AI fit analysis against its position: match score and sub-scores (skills, experience, seniority), any interviewer override, summary, strengths, gaps, skills, years of experience, recent roles and education. Red flags are signals for a person to review, not a verdict. The resume id comes from list_resumes.
get_resume_batch
ChatGPTGet one resume upload batch's progress counts and position. The batch id comes from list_resume_batches.
get_session_results
ChatGPTGet a candidate session's full results for grading: each submission's code, test results, auto score, MCQ review, AI grade with sub-scores, reasoning, feedback and suggestions, who decided the grade and the final score, the candidate's verdict and its reasoning (review rounds), the size of each conversation (transcript.turns; the full agentic chat or take-home follow-up discussion is in get_submission), the composite score, the take-home PR with its diff (the candidate's changes), its description (prBody), branches (baseRef, headRef) and commits, behavioral counts and the session cheating check. The session's grading summary (gradingSummary: a one-line headline, up to three strengths and three concerns, written by the AI after the rounds are graded; null until then) is the quickest answer to "how did they do". sessionGradingState says where the sitting is (NOT_FINISHED, GRADING, GRADED, APPROVED, FLAGGED, GRADING_FAILED, NOT_GRADED, PASSED, FAILED) with gradingProgress over the AI-graded rounds; gradingFlaggedAt set means the integrity check held auto-publishing for a person. The candidate's take-home repository is private: prUrl does not open for the user; the whole pull request is on the app's pull request page, whose link is takehomeState.pullRequestPage (for a signed-in teammate). takehomeState is the first take-home of the sitting. Each coding submission's tests are summarised as testSummary (passed, total, the first failure); get_submission has every case with its output. MCQ submissions read aiGradeStatus AUTO_GRADED: they are scored on submit, their finalScore is final and they need no approval. Integrity fields (cheatingRiskScore, cheatingIndicators, promptInjectionFlags, ownership verdict) are signals for a person to review, never a verdict. timeSpentSeconds is the session length in seconds. compositeScoreStatus PARTIAL means some grades are still undecided, so there is no composite yet. The submission cheatingRiskScore is per question; the session's cheatingCheck.cheatingRiskScore is the whole-session signal, and a null cheatingCheck means it has not run yet, not that the session is clean. The sessionId comes from the candidate or session lists.
get_shortlist_share
ChatGPTReturns one shortlist in full: its settings and every candidate with score, recruiter note and the client's answer and comment.
get_stage_email_preview
ChatGPTReturns the company's email draft (subject and Markdown body) for moving a candidate into a human stage (interview, client review, offer, hired), with the Reply-To address and whether {bookingLink} resolves. Use it to prefill the email argument of move_candidate_to_stage. Sends nothing. stageId comes from get_position_pipeline; pass positionCandidateId to resolve that candidate's names.
get_submission
ChatGPTGet one submission in full: the candidate's code, the full conversation (chatTranscript: every turn of an agentic round's chat, or of a take-home's follow-up discussion about their PR), test results with the failing cases' output and errors, the MCQ review per question or the agentic verdict with its reasoning, an AI interview's answers (the question as asked, the transcript, its duration, speakers and language; the video itself is watched in the app), and the AI grade with its written feedback and who decided it. Use it after get_session_results when you need to read the work itself, e.g. "show me the follow-up transcript" or "what did they write". The submission id comes from get_session_results.
import_sheet_rows
ChatGPTCopies the people of one tab of a connected sheet's spreadsheet onto the Hireinator tab as new rows, using the column mapping the user confirmed. Creates no candidates, invites or emails: the rows start with the Action column blank, and the recruiter picks Send test per row. People already on the tab are skipped, and so are rows that look like an edit of someone already there (skippedChanged). skippedOverLimit above 0 means the tab is over the 500-row limit, never a count. The mapping is saved for sync_sheet_import.
invite_candidate
ChatGPTInvite one candidate to take an assessment: creates their candidate session and emails them the test link (valid 7 days). If the candidate already holds a live session for this assessment it is reused and no second email goes out: a createdAt older than this call means reused, so say no email was sent. The result proves the invite was recorded, not that the email was delivered. Sending an invite is free; credits are spent only when the candidate starts the test (get_assessment_credit_cost says how many). Get assessmentId from the assessment list and positionId from the positions list; linking a position opens their journey in its hiring process.
invite_candidates_bulk
ChatGPTInvite a list of candidates (up to 500) to one assessment in a single call; every newly invited candidate is emailed their test link. Candidates who already hold a session for the assessment are reported as ALREADY_INVITED and not emailed again. Sending an invite is free; credits are spent only when the candidate starts the test (get_assessment_credit_cost says how many). Each link is valid for 7 days. With positionId on a row, position may be left empty: the position's title is used. Returns per-row status (INVITED, ALREADY_INVITED, FAILED with the reason).
invite_screened_resumes
ChatGPTTurn screened resumes into test invites (up to 200): each resume's candidate is emailed a test link for the resume position's default assessment, or for assessmentId when given. Name and email come from the resume unless you override them per row. Sending an invite is free; credits are spent only when the candidate starts the test (get_assessment_credit_cost says how many). Resume ids come from list_resumes. Returns per-row status.
invite_teammate
ChatGPTCreates a teammate account in the caller's company and emails them a one-time link to set their own password; the account stays inactive until they do. Role is INTERVIEWER (team member) or COMPANY (a fellow admin who can change settings, credits and the team). To invite a candidate to a test, use the candidate invite tools instead.
list_analytics_positions
ChatGPTLists the position names that have candidate sessions visible to the caller, for use with list_decided_candidates. Agency accounts may narrow to one client.
list_apply_links
ChatGPTLists the company's apply links (one public application form per position): the position, whether it is closed, views, how many applications came in, the public description the applicant reads, the company's own questions on the form and the hiring steps (processNote, one per line). url is the full link for a link made since the token is stored; an older one shows only its tokenPrefix until it is regenerated. The role facts the page shows (location, work mode, salary, skills) live on the position: get_position.
list_assessment_templates
ChatGPTLists Hireinator's pre-built role screens (for example a backend engineer screen) with their suggested challenges from the shared library. Use one as the starting point for create_assessment when there is no job description to recommend from.
list_assessments
ChatGPTLists the company's assessments (tests) with status (DRAFT, PUBLISHED, ARCHIVED) and their challenges' titles and types. Use it to find an assessmentId. Paged: 50 by default, at most 100.
list_candidate_notes
ChatGPTLists the team's private notes on a candidate (Markdown body, author, mentioned teammates, the session or journey it was attached to). candidateId is the Candidate id (candidate.id on a session or journey), not a session id.
list_candidate_sessions
ChatGPTLists the company's candidate test sessions (one per candidate per assessment), newest first, with status, composite score, decision, position, client and journey stage, plus total: how many match the filters. Filters: candidateId, assessmentId, positionId, clientId, status (NOT_STARTED, IN_PROGRESS, PAUSED, COMPLETED, EXPIRED), decision (PASSED, FAILED or UNDECIDED), minCheatingRisk (session or any per-question risk at or above it; a signal to review, not a verdict), createdAfter/createdBefore (the invite date) and completedAfter/completedBefore. Paged: 25 by default (limit up to 100), offset for the next page; say when total is larger than what you read. Archived sessions are hidden unless includeArchived is true. To find one person by name or email use find_candidates; for what to act on today use list_needs_attention. journey.id is the positionCandidateId the stage tools need.
list_candidate_tags
ChatGPTLists the company's candidate tags (id, name, colour). Tag ids are what set_candidate_tags, update_candidate_tag and delete_candidate_tag take.
list_challenges
ChatGPTLists challenges the company can use: Hireinator's shared library (company null) and the company's own, newest first, with type (CODING, AGENTIC_CODING, MCQ, TAKE_HOME, INTERVIEW: the AI interview, recorded video answers graded from the transcript), difficulty and the programming languages offered. Filter by challengeType, difficulty, language (e.g. Go) and search (words in the title or description, e.g. kubernetes); an MCQ quiz names its topic in the title. Paged: 50 by default, at most 100; page with offset.
list_clients
ChatGPTLists an agency's client companies with open positions, candidates in flight and the last shortlist date. Only agency accounts use clients; an in-house company has none.
list_decided_candidates
ChatGPTLists the candidates with a final decision for one position name (from list_analytics_positions): assessment, completion and decision dates, decision (APPROVED or REJECTED), composite score (0 to 100) and letter grade. Use it to compare the people who went through a role.
list_email_templates
ChatGPTLists every candidate email the company sends with its current subject, Markdown body, whether it is still the default, and the placeholders that kind accepts. Read this before editing a template. What sends each kind: INVITATION an invite or resend (invite_candidate, bulk invites, a move into an assessment stage); COMPLETION the candidate submitting their test; TAKEHOME_PR_RECEIVED their take-home pull request arriving; TAKEHOME_REMINDER automatically, once, when a take-home deadline is under 24 hours away and no PR has arrived; DECISION_PASSED and DECISION_FAILED submit_final_decision; STAGE_INTERVIEW, STAGE_CLIENT_REVIEW, STAGE_OFFER and STAGE_HIRED a stage move sent with its email argument. Language: a template the company saved is sent exactly as written to every candidate, whatever their language (EN or JA), while a kind still on the default goes out in each candidate's own language. So a company with Japanese candidates either keeps the defaults or writes a template that works for both. The parts added around the body (button, details card, signoff, footer) always follow the candidate's language. A candidate's language is set at invite: the company's default candidate language if it has one (get_my_company candidateLanguage), else the inviting person's. Previews and test emails render in the company's language.
list_my_notifications
ChatGPTLists the signed-in user's in-app notifications (such as a teammate mentioning them in a candidate note), newest first, with the unread count. Use mark_notifications_read to clear them.
list_needs_attention
ChatGPTThe recruiter's inbox: what to act on now, oldest first. toGrade: finished tests with answers still to grade; each detail says how many AI grades are ready to approve, reject or override, how many are being graded, and how many were never graded (run_ai_grading); toDecide: tests whose grades are all decided but with no PASSED/FAILED decision (submit_final_decision); expiringInvites: invites not started that expire within 24 hours (resend_candidate_invite extends them); expiredInvites: invites that expired unstarted in the last 30 days (resend_candidate_invite sends the same link again for 7 days); stalledJourneys: active candidates unmoved in their stage for stalledDays (default 7), and each detail says why (on an Assessment stage: the test not started, its invite expired, in progress or completed with its score), so answer from it without looking people up again. Each list is capped at limit (default 20) with its full total; since is when the wait started (for expiringInvites, the moment the link expires). Use it for "what should I do today" or "who is waiting on me". Archived candidates are left out.
list_positions
ChatGPTLists the company's positions (job openings) with status, client and default assessment. Use it to find a positionId. Descriptions are left out; get_position returns one in full with its hiring process.
list_preview_links
ChatGPTLists the preview links the company has made: who each is for (label), the role title, the questions with their pitch lines, expiry, revoked, views, last viewed, and per question what the viewer did (activity: viewedAt, runs, turns). url is the full link for a link made since the token is stored; an older one shows only its tokenPrefix until it is regenerated.
list_programming_languages
ChatGPTLists the programming languages a coding challenge can offer, with their ids for create_challenge and update_challenge languageTemplates.
list_resume_batches
ChatGPTList resume upload batches with their position and progress counts (pending, processing, analyzed, failed, unparseable, invited). Useful to check whether a recent upload has finished screening.
list_resume_positions
ChatGPTList the positions that have resumes screened with AI, with counts (total, still processing, analyzed, invited, strong matches scoring 70 or more) and the top score. Start here to find a positionId for list_resumes.
list_resumes
ChatGPTList screened resumes with their AI match score (effectiveScore is the interviewer override when set, else the AI score), status and parsed name and email. Filter by positionId (most common), batchId or candidateId; at least one is required. Use get_resume_analysis for one resume's full fit analysis.
list_sheet_controls
ChatGPTLists the Google Sheets connected as control surfaces (a tab where recruiters pick actions per candidate row): id, link, tab, whether it is active and why not, default assessment and position, the acting user whose company's credits the sheet's actions use, last successful sync, row count, the registered resume folder and the instant-updates state.
list_sheet_import_tabs
ChatGPTLists the other tabs of a connected sheet's spreadsheet that candidates can be imported from (the customer's own lists; the Hireinator tab itself is left out). The first step of importing: then analyze_sheet_import, import_sheet_rows, and later sync_sheet_import.
list_shortlist_shares
ChatGPTLists the shortlists the agency has sent to clients: title, client, expiry, revoked, views, and each candidate with the client's answer (INTERESTED, NOT_NOW, PASS). The link itself cannot be read back; only its tokenPrefix.
list_team_members
ChatGPTLists the company's user accounts with id, email, name, role (COMPANY is an admin, INTERVIEWER a team member) and status (INACTIVE means an invite not yet accepted). Use it to find a userId for resend_teammate_invite, change_teammate_role or remove_teammate.
list_teammates
ChatGPTLists the active users of the company (id and names). Use the ids as mentionUserIds when adding a note that should notify a teammate.
list_webhook_deliveries
ChatGPTLists recent deliveries to one webhook endpoint (id from get_integrations_status), newest first: event type, status, attempts, last response code and error, next retry. Use it to diagnose a failing endpoint.
mark_notifications_read
ChatGPTMarks the signed-in user's in-app notifications as read: the given ids, or all of them when ids is omitted or empty. Returns how many changed. Ids come from list_my_notifications.
move_candidate_to_stage
ChatGPTMoves one candidate's journey to another stage of the same position. Moving into an ASSESSMENT stage invites the candidate to that stage's test and emails them the link unless they already hold a session for it (credits are spent only when they start). With the optional email argument, a move into a human stage emails the candidate (Reply-To you); nothing is sent without it. alreadyAtStage true means the candidate was already at that stage (perhaps moved moments ago by someone else): nothing moved and NO email was sent, so tell the user; there is no way to send a stage email without a move. A move never records a decision on the candidate's test: if their test is finished but undecided (decision UNDECIDED), ask whether to record PASSED too with submit_final_decision (that emails the result separately; with the position's pass-advances switch on, PASSED alone also moves them one stage, without the interview details). positionCandidateId and stageId come from get_position_pipeline.
move_candidates_to_stage
ChatGPTMoves several journeys of one position to the same stage and reports per-candidate failures. Same side effects as move_candidate_to_stage for each candidate: an ASSESSMENT stage invites (and emails) anyone without a session for its test, and the optional email is sent to every moved candidate with placeholders filled per candidate.
override_resume_score
ChatGPTSet an interviewer's own match score (0 to 100) and note on a screened resume, replacing the AI score for ranking; pass score null to clear the override and go back to the AI score.
preview_email_template
ChatGPTRenders a draft subject and body for one email kind with sample values and the company's branding, without saving anything. Returns the rendered subject and the plain-text version. Use it to check a draft before update_email_template.
preview_sheet_import
ChatGPTCounts the people in one tab of a connected sheet's spreadsheet who are not on the Hireinator tab yet (newRows) and those already there (alreadyPresent). overLimit true means the tab is longer than one import reads (500 rows), so newRows is a lower bound: say the tab is over the limit, never quote it as a total. Free; nothing is changed.
publish_assessment
ChatGPTPublishes an assessment so candidates can be invited to it. Publishing itself emails nobody and spends nothing; confirm the challenges with the user first.
reanalyze_resume
ChatGPTQueue a finished (analyzed, failed or unparseable) resume for a fresh AI analysis, for example after the position's description or screening notes changed. The new analysis replaces the old one when it completes; an interviewer override score is kept. It spends no credits (the metered part of screening is the upload).
recommend_assessment
ChatGPTAsks the AI to pick challenges from the catalog for a job description (a position's description and screening notes, or pasted text) and returns them with reasons, a suggested title, difficulty and duration, and uncoveredSkills: testable skills no catalog challenge covers (certifications and years of experience are never listed; they are not testable). With no fitting challenge, challenges is empty and there is no title, difficulty or duration; report the gaps and offer submit_challenge_request (never for a non-technical role: the product does not test those). creditsPerCandidate is what each candidate who starts the recommended test would spend. suggestedDurationMinutes is the in-app time only: a take-home adds its takehomeExpectedHours of the candidate's own time over takehomeDeadlineDays. Free: no credits. The result is saved and served again for the same text unless refresh is true. It creates nothing; pass the picks to create_assessment.
refresh_takehome_snapshot
ChatGPTRe-fetch a candidate's take-home pull request snapshot (diff and stats) from GitHub, for example when a webhook was missed and the PR shows as pending. Refreshes the artifact only, never the grade. challengeId is the take-home challenge (takehomeState.challengeId in get_session_results).
regenerate_apply_link
ChatGPTIssues a new URL for the same apply link and returns it: the old URL stops working at once (a job ad that carries it must be updated). The form and the applications are kept. Refused on a closed link (create_apply_link reopens one).
regenerate_challenge_translation
ChatGPTTranslates a challenge's candidate-facing text again with AI and replaces the cached translation, which then needs review. No credits. Only the company's own challenges.
regenerate_shortlist_share_link
ChatGPTIssues a new URL for the same shortlist and returns it once: the old link stops working at once and the expiry restarts. Use it when a link was lost or forwarded too widely. Refused on a revoked share.
reject_ai_grade
ChatGPTReject the AI grade on a submission. With overrideScore (0 to 100) that number becomes the final score; without it a coding submission falls back to its test-case auto score and an agentic or take-home one has no score. Updates the session composite score. The submission id comes from get_session_results.
reject_journey
ChatGPTRejects a candidate's journey at a position where it stands (reopen_journey undoes it). Emails the candidate the standard rejection only when emailCandidate is true. It records no verdict on any test: for a candidate who completed a test, use submit_final_decision with FAILED, which records the result and rejects the journey in one step. positionCandidateId comes from get_position_pipeline or list_candidate_sessions (journey.id).
remove_teammate
ChatGPTRemoves a teammate from the company and ends all their sessions; their assessments and results stay with the company. You cannot remove yourself or the last active admin. companyId is the caller's company id from get_my_company; confirm with the user first.
reopen_journey
ChatGPTReopens a rejected or withdrawn journey so the candidate is active again at the stage where it stopped. Emails nobody. positionCandidateId comes from get_position_pipeline (use includeArchived for archived ones) or list_candidate_sessions (journey.id).
replace_interview_question
ChatGPTDrafts ONE replacement for a question of an AI interview draft that fits the rest of the set (no repeated topic, not a rewording of the one replaced), with its own secret rubric, clarification, answer limit and follow-up switch. Creates nothing: pass the whole current draft (1 to 8 questions, the slot included), the 0-based index of the slot and optionally what the user did not like about it, then put the result in that slot before create_challenge. Costs an AI call, never credits. Emails nobody.
resend_candidate_invite
ChatGPTEmail the candidate their test link again (the same link, still valid) and extend the invite's expiry by 7 days from now. Only works while the session is NOT_STARTED and not archived (restore_candidates first); a started test that ran out of time (EXPIRED) cannot be reopened. To cancel an invite sent by mistake, archive the session with archive_candidates (the link stops working; the email already sent cannot be recalled). Every call sends another email. The link itself is never returned (it is the candidate's credential and only goes to their inbox), so an assistant cannot hand it over for WhatsApp or chat; the candidate uses the emailed one. The sessionId comes from the candidate or session lists.
resend_teammate_invite
ChatGPTEmails a pending (INACTIVE) teammate a fresh set-password link; the previous link stops working. Get the userId from list_team_members.
reset_email_template
ChatGPTDeletes the company's custom wording for one email kind so the hireinator default is used again (the default comes in each candidate's language). The custom text is lost; confirm with the user first.
restore_candidates
ChatGPTRestores archived candidates (by sessionIds or positionCandidateIds) so they show again and their invite links work. Find archived ones with list_candidate_sessions or get_position_pipeline with includeArchived true. Returns how many candidates changed.
restore_client
ChatGPTRestores an archived agency client to active. Find archived ones with list_clients includeArchived true.
retry_sheet_script
ChatGPTClears a failed install of a connected sheet's instant-updates script (scriptStatus and scriptLastError in list_sheet_controls) so the next sync tries again; it does not install anything itself. Refused on a sheet connected through the shared service account, where Google does not support the script.
retry_webhook_delivery
ChatGPTRe-queues one failed or dead webhook delivery (id from list_webhook_deliveries) so it is sent again to the customer's endpoint.
review_challenge_translation
ChatGPTMarks a challenge's translation as reviewed by the user, clearing needsReview. Only after the user has actually read and accepted it.
revoke_preview_link
ChatGPTKills a preview link immediately: the page answers not found from then on. Cannot be undone; make a new link with create_preview_link instead.
revoke_shortlist_share
ChatGPTKills a shortlist's link immediately; the client can no longer open it or answer. Cannot be undone (a revoked share cannot get a new link).
run_ai_grading
ChatGPTStart AI grading of one submission; it runs in the background, so poll get_ai_check with the returned id. If a check is already running for the submission, that one is returned instead. Re-running on a graded submission is a regrade whose score replaces the current AI score when it completes. AI grading is included in the credits the candidate's start already spent; a take-home cannot be graded before the candidate starts the session. A finished grade still waits for a person: approve_ai_grade, reject_ai_grade or submit_manual_grade decides it.
run_cheating_check
ChatGPTRun the session-level integrity analysis over the candidate's behavioral signals (tab switches, fullscreen exits, paste counts and the like), replacing any earlier one for the session. The result is a risk signal for a person to review, never a verdict, and it never changes a score. Included in the session's credits.
send_test_email
ChatGPTEmails the signed-in user (only them) the current saved template of one kind, with sample values and the company's branding; the reply names the address it went to. Allowed once every 30 seconds per company.
set_candidate_tags
ChatGPTSets a candidate's tags to exactly the given list (tags left out are removed; an empty list clears them). candidateId is the Candidate id (candidate.id on a session or journey); tag ids come from list_candidate_tags.
set_sheet_instant_updates
ChatGPTTurns off (disabled true) or back on the instant-update callbacks of one connected sheet. Off means actions picked in the sheet run on the normal sync instead of within seconds; it does not remove the script from the spreadsheet, and on cannot install a script that is not there.
submit_challenge_request
ChatGPTAsks the Hireinator team to build challenges for skills the catalog cannot test yet, typically the uncoveredSkills from recommend_assessment (testable skills only, not certifications or years of experience). The request is recorded and the team is notified; nothing reaches candidates. Confirm the skills with the user first.
submit_final_decision
ChatGPTRecord the hiring decision on a candidate's TEST (a session), PASSED or FAILED, and email the candidate the result with your optional personal note. This is the tool for a candidate who took a test: it records the verdict on their results, and the journey follows (PASSED moves them one stage forward when the position's pass-advances switch is on, but only while they still sit at this test's stage: someone already moved on by hand stays where they are; FAILED rejects their journey where it stands and always emails the result). Use reject_journey instead only to drop someone with no test to decide (at a screen or interview stage). Repeating the same verdict sends no second email; changing it emails again. decisionEmailQueued in the reply says whether this call queued the email; journey shows where the candidate now stands.
submit_final_decisions
ChatGPTRecord the same hiring decision, PASSED or FAILED, on several candidates' tests at once and email each candidate the result with your optional personal note. Only a session whose every round is decided takes the verdict; the others are skipped with the reason. The same guard as submit_final_decision: an unchanged verdict sends no second email (emailed counts the sessions that were), and each journey follows as it does there.
submit_manual_grade
ChatGPTGrade a submission yourself, bypassing the AI: the 0 to 100 score becomes the submission's final score (never capped). Updates the session composite score.
sync_sheet_import
ChatGPTBrings the new people of a tab imported before onto the Hireinator tab, with the mapping saved at that import (so it works only on a tab import_sheet_rows has run on). Reads the whole tab, never re-adds someone whose row was deleted from the Hireinator tab, and creates no candidates, invites or emails. Fails naming the column when a heading was renamed; import_sheet_rows again repairs the mapping.
sync_sheet_now
ChatGPTAsks for a connected sheet to be checked right away instead of at its next scheduled check; the check runs in the background, so the returned row is the state before it. Any actions picked in the sheet (which can send invites or emails) run in that check. A press within the rate-limit window is dropped silently; refused on a paused sheet.
test_webhook_endpoint
ChatGPTSends a signed test ping to one webhook endpoint (id from get_integrations_status) on the customer's own server and returns whether it answered successfully, with the status code or error.
test_workday_connection
ChatGPTRe-runs the live credential check against the company's Workday tenant and revives a paused connection when it passes. Returns ok and a message.
update_apply_link
ChatGPTChanges an apply link's form: the public description the applicant reads, the company's own questions and the "How hiring works" steps. Only what you pass changes; fields replaces the whole list of questions (an empty list removes them all). Answers already given keep the question wording they were given under. The URL stays the same. The role facts on the page live on the position (update_position).
update_assessment
ChatGPTChanges an assessment; only the fields given change, and challengeIds replaces the whole challenge list. Use publish_assessment and archive_assessment to change status. On a PUBLISHED assessment the change is live at once: every invited candidate who has not started gets the new version (and its credit cost, used when they start), and a candidate mid-test may see changed questions on their next load; finished results are kept. Tell the user this and confirm before changing a published test's challenges or duration.
update_candidate_tag
ChatGPTRenames or recolours a candidate tag; every candidate carrying it shows the change. The id comes from list_candidate_tags.
update_challenge
ChatGPTReplaces a company challenge's content. It is a full replacement: send every field, including ALL languageTemplates and testCases, or the missing ones are removed (MCQ questions are kept as they are; an AI interview's interviewQuestions list replaces the bank, a question with its id is updated in place; a take-home's takehomeDebriefMode is kept when left out). Library challenges are read-only. Cached translations are regenerated in the background.
update_client
ChatGPTChanges an agency client; only the fields given change. Turning revealToCandidates on names the client to candidates in the test and emails, so do that only on the user's explicit instruction.
update_company_hiring_template
ChatGPTReplaces the company's template stages and/or the pass-advances switch. Changes propagate to every position that has not customized its own process (candidates never move). Company admins only. Stage kinds: SCREEN (must be first, exactly one), ASSESSMENT (a test; assessmentId omitted means the position's default assessment, at most one stage may rely on that, and an assessment may appear only once), CLIENT_REVIEW (agencies: submitted to the client), INTERVIEW, OFFER, HIRED (must be last).
update_company_settings
ChatGPTChanges the company profile: name, description, website, admin email, account type (COMPANY or AGENCY; AGENCY turns on clients), company language (also the language AI writes team-facing prose in), the default candidate invite language, and the company booking link. Only the fields you pass change. Get the id from get_my_company and confirm the change with the user first.
update_email_branding
ChatGPTChanges how candidate emails look: the brand colour (header, button and note border), the sender display name (candidates see "{name} via hireinator"; the sending address never changes) and the Reply-To address. To clear a field back to the default send "default" (an empty string works too); omitted fields are unchanged. The logo is uploaded in the browser on the company profile page.
update_email_template
ChatGPTLanguage: a template the company saved is sent exactly as written to every candidate, whatever their language (EN or JA), while a kind still on the default goes out in each candidate's own language. So a company with Japanese candidates either keeps the defaults or writes a template that works for both. The parts added around the body (button, details card, signoff, footer) always follow the candidate's language. A candidate's language is set at invite: the company's default candidate language if it has one (get_my_company candidateLanguage), else the inviting person's. Previews and test emails render in the company's language. Saves the company's wording for one candidate email kind; every later email of that kind uses it. The body is a Markdown subset: and headings, "- " and "1. " lists (no nesting), bold, italic, ++underline++ and label links. Placeholders like {candidate} must be in the kind's list from list_email_templates (unknown ones are refused); only {meetingLink} and {bookingLink} may be a link destination. The token link, details card, signoff and footer are added automatically and cannot be edited. Every kind except the four STAGE_ kinds already ends with a signoff (the inviter's name on the invitation, "The {company} team" on the rest), so do not end those bodies with {recruiter} or a "Best regards" line (it would print twice); a STAGE_ body carries its own signoff. Candidate emails come from a no-reply address: never write "reply to this email" unless the company set a Reply-To (get_my_company emailReplyTo). The four STAGE_ kinds are the exception: their Reply-To is always the recruiter who sends them. update_my_profile
ChatGPTChanges the signed-in user's own booking link and language (never anyone else's). The booking link must be https (empty string clears it) and becomes {bookingLink} in stage emails this user sends. Omit a field to leave it unchanged.
update_position
ChatGPTChanges a position; only the fields given change. Use status CLOSED to close an opening (or OPEN to reopen it). Editing the description invalidates the saved assessment recommendation for it. Emails nobody.
update_position_hiring_process
ChatGPTChanges one position's hiring process: its stages, the pass-advances switch, or a reset to the company template. Editing stages marks the position customized. An ASSESSMENT stage's autoRule acts on its own when a candidate's score is final: it rejects below rejectMaxScore (a score equal to it is not rejected; emailing them only if rejectEmail is true) and advances at or above advanceMinScore, and it only ever advances into a next stage that is another ASSESSMENT: when the next stage is an interview, offer or hired, the advance part never fires (a person moves them, or a PASSED decision does when passAdvancesStage is on). Either threshold may be null to leave that half off. So "reject under 70" is rejectMaxScore 70 and "advance from 70" is advanceMinScore 70; a score between the two waits for a person. Saving a rule touches nobody: it runs only when a score lands final afterwards (a grade changed later counts). An automatic reject closes the journey (REJECTED) but records no FAILED decision on the test; with rejectEmail true the candidate gets the standard FAILED result email. Stage kinds: SCREEN (must be first, exactly one), ASSESSMENT (a test; assessmentId omitted means the position's default assessment, at most one stage may rely on that, and an assessment may appear only once), CLIENT_REVIEW (agencies: submitted to the client), INTERVIEW, OFFER, HIRED (must be last).
update_sheet_control
ChatGPTChanges a connected sheet's name, pauses or resumes it (active), sets its default assessment and position, or registers the Google Drive folder "Screen resume" may read from (an empty string unregisters it, which stops resume screening from that sheet). Only the fields you pass change.
update_shortlist_share
ChatGPTChanges a live shortlist: title, note, the contact and integrity switches, the expiry, or which candidates it shows. The client sees changes immediately on the existing link.
withdraw_journey
ChatGPTMarks a candidate's journey as withdrawn (the candidate dropped out). Emails nobody; reopen_journey undoes it. positionCandidateId comes from get_position_pipeline or list_candidate_sessions (journey.id).
