Applicant Tracking: Onsite Loops, Duplicate Candidates and Offer Approvals

Applicant Tracking: Onsite Loops, Duplicate Candidates and Offer Approvals

You've joined the recruiting-tools team at a mid-size company. Their applicant tracking system (ATS) moves candidates through a hiring pipeline per job requisition, and it already works for the basics. Three tickets are queued: the onsite interview loop with its hiring decision (plus a metrics bug), merging candidates who applied twice, and a compliance-driven offer approval flow with headcount. Each Part builds on the previous one, and a Part 3 rule changes how Part 1 behaved, so keep your earlier tests running as you go.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh ATS and returns one result per operation. Every operation is [name, at, *args]; at is an integer number of seconds and never decreases. A success returns the operation's value (below); a failure returns the string "error: <code>", e.g. "error: bad transition". Errors are returned, never raised, and a failed operation changes nothing.

A request that is not a list, has a non-string name, a non-integer at (true/false are not integers), too many arguments, or a missing or wrongly typed argument returns error: bad request; an unknown name returns error: unknown op. The ROUTES table in api.py is the source of truth for argument order and types; a trailing optional argument may be omitted or null.

Part 1 operations (errors are checked in the order listed)

• apply creates the candidate on first sight (candidate is the id you choose) and stores name, the normalised email and, if usable, the normalised phone. Applying again with an existing candidate id to a different requisition adds an application and ignores the other arguments (they are still validated: an unusable email is invalid email). Applying twice to the same requisition is already applied. A phone that does not normalise to ten digits is simply not stored. Rules for "usable" are in ats/normalize.py.
• Stages are applied -> screen -> onsite -> offer -> hired. From applied, screen, onsite or offer an application may also go to rejected or withdrawn. Those three are final. Any other move (skipping a stage, going backwards, leaving a final stage, or a made-up target name) is bad transition. reason is stored only when moving to rejected or withdrawn; application returns it (null otherwise).
• seed and seed_pairs are load-test fixtures; AtsService.seed / seed_pairs show exactly what they do. seed applies count generated candidates s0, s1, ... to req at at, with emails that collide when i % mod is equal, and moves every screen_every-th one (i % screen_every == 0, 0 disables) to screen at at + 60. seed_pairs creates pairs couples p<i>/q<i> with the same address and drives each to a pseudo-random depth using the seed rng.

Part 1: The onsite loop and the hiring decision (TALENT-398, TALENT-412)

Goal: coordinators need interviewers to submit scorecards for a candidate's onsite loop, a hiring decision computed from them, and a gate so nobody reaches offer without a positive decision. Separately, recruiting ops report that time-in-stage numbers for rejected candidates keep growing.

A scorecard score is -2 (strong no), -1 (no), 0 (neutral), 1 (yes) or 2 (strong yes).

1. scorecard records one card per interviewer for an application; interviewer must contain a non-space character (invalid interviewer) and score must be one of the five values (invalid score). The application must have been in onsite at some point, even if it has since moved on or been rejected (not at onsite). A second card from the same interviewer replaces the first. The result is [late, count]: count is the number of cards now stored for the application.
2. close_loop decides the loop. The application must be currently at onsite. Fewer than 3 stored cards is need 3 scorecards (nothing is decided and the loop stays open). Otherwise, with *n* cards, the average is the exact fraction sum / n and the decision is "advance" if no card is -2 and the average is at least 1; otherwise "decline". average is str(Fraction): "1", "4/3", "-1/2", "0". counted is *n*. A loop can be closed only once.
3. The decision is a snapshot. A card submitted after close_loop (including a resubmission replacing an earlier card) is stored and returned with late = true, but never changes the decision or the average. Cards submitted before the close have late = false.
4. scorecards returns [decision, average, cards]; decision and average are null until the loop is closed, and cards is a list of [interviewer, score, late] in string order of interviewer name.
5. move to offer additionally requires an "advance" decision for that application, else not cleared for offer (checked after bad transition). Moves to rejected / withdrawn never need a decision, and a "decline" can never be reversed.
6. Time in stage. An application spends a *spell* in each active stage (applied, screen, onsite, offer): from the at it entered the stage to the at it left it, where leaving includes going to rejected, withdrawn or hired. Final stages have no spell. stage_report returns four [stage, spells, seconds] rows in pipeline order covering all applications of the requisition; a spell that is still open counts up to the report's at.

Example 1

[["open_req", 0, "r1", "Backend Engineer"],
 ["apply", 10, "r1", "ana", "Ana Ruiz", "ana@example.com"],
 ["move", 100, "ana", "r1", "screen"],
 ["move", 200, "ana", "r1", "onsite"],
 ["scorecard", 300, "ana", "r1", "dee", 2],
 ["scorecard", 310, "ana", "r1", "eli", 1],
 ["scorecard", 320, "ana", "r1", "fay", 0],
 ["close_loop", 400, "ana", "r1"],
 ["move", 500, "ana", "r1", "offer"],
 ["stage_report", 700, "r1"]]

returns (one result per operation)

[true, "applied", "screen", "onsite", [false, 1], [false, 2], [false, 3],
 ["advance", "1", 3], "offer",
 [["applied", 1, 90], ["screen", 1, 100], ["onsite", 1, 300], ["offer", 1, 200]]]

Example 2 (a veto, a late card and the gate; bo is already at onsite)

[["scorecard", 10, "bo", "r1", "dee", 2], ["scorecard", 11, "bo", "r1", "eli", 2], ["scorecard", 12, "bo", "r1", "fay", 2],
 ["scorecard", 13, "bo", "r1", "gus", -2], ["close_loop", 14, "bo", "r1"], ["scorecard", 15, "bo", "r1", "hal", 2],
 ["scorecards", 16, "bo", "r1"], ["move", 17, "bo", "r1", "offer"]]

returns

[[false, 1], [false, 2], [false, 3], [false, 4], ["decline", "1", 4], [true, 5],
 ["decline", "1", [["dee", 2, false], ["eli", 2, false], ["fay", 2, false], ["gus", -2, false], ["hal", 2, true]]],
 "error: not cleared for offer"]

The average is 1, but the strong no vetoes it; hal's late card is kept (flagged) and changes nothing.

Part 2: Duplicate candidates and merging (TALENT-455)

Goal: candidates apply twice under different ids ("ana@example.com" and "Ana+jobs@Example.com"). Recruiters need to find those duplicates and merge them into one candidate without losing or double-counting anything.

New operations:

1. Two candidates are *duplicates* if they share a normalised email or a normalised phone (see normalize.py: lower-case, +tag stripped from the local part; phone is the ten national digits). The relation is transitive: if A shares an email with B and B shares a phone with C, then A, B and C form one group. A candidate matches on every email and phone it has accumulated (see rule 6).
2. duplicates returns total (number of groups) and groups: each group is a list of candidate ids (two or more) ordered oldest-created first; groups are ordered by their oldest member; limit keeps only the first limit groups (total still counts all). Merged-away candidates never appear.
3. merge folds duplicate into primary; errors are unknown candidate (primary checked first), then same candidate (after resolving merged ids, see rule 6). Recruiters may merge any two candidates; they need not be flagged as duplicates. For each requisition:

• if only one of them has an application, it simply moves to the primary;
• if both do, keep one: the one in the more advanced stage, ranked hired > offer > onsite > screen > applied > rejected > withdrawn. At equal rank keep the one with the earlier applied_at; if that also ties, keep the primary's. The kept application keeps its own stage, reason, applied_at, creation order, scorecards (cards and decision) and stage history. Everything recorded for the other application, including its time-in-stage spells and scorecards, is discarded: stage_report must count only surviving applications.

1. merge returns the primary's id and applications: [req, stage] pairs for the merged candidate, sorted by requisition id.
2. merge_all merges every duplicate group (as of the moment it is called) into its oldest-created member, merging the others in creation order, and returns the number of candidates folded away.
3. After a merge the duplicate's id is an alias of the primary: every operation that takes a candidate accepts it and acts on the primary (including apply with a new requisition). Aliases chain (merge A into B, then B into C, and A resolves to C). The primary keeps its own name; it also gains the duplicate's emails and phones, so a later applicant sharing the old address is a duplicate of the primary.
4. candidate returns the canonical id, name, emails and phones (sorted lists of normalised values), aliases (ids merged into it, in merge order; a candidate's own aliases follow it) and applications (as in rule 4).
5. Earlier behaviour is unchanged. Merges and duplicates must stay fast on thousands of candidates and applications; a merge_all over a few thousand candidates is part of the hidden tests.

Example (after open_req r1 and r2)

[["apply", 10, "r1", "ana", "Ana Ruiz", "ana@example.com", "(555) 010-2000"],
 ["move", 20, "ana", "r1", "screen"],
 ["apply", 30, "r1", "ana2", "A. Ruiz", "Ana+jobs@Example.com", "1-555-010-2000"],
 ["apply", 40, "r2", "ana2", "A. Ruiz", "x@y.io"],
 ["duplicates", 50],
 ["merge", 60, "ana", "ana2"],
 ["application", 70, "ana2", "r2"],
 ["stage_report", 100, "r1"]]

returns

["applied", "screen", "applied", "applied",
 [1, [["ana", "ana2"]]],
 ["ana", [["r1", "screen"], ["r2", "applied"]]],
 ["applied", null],
 [["applied", 1, 10], ["screen", 1, 80], ["onsite", 0, 0], ["offer", 0, 0]]]

Part 3: Offers, approvals and headcount (TALENT-501)

Goal: Finance wants every offer approved by a chain of people that depends on the salary, wants any change to an offer to restart its approvals, and wants requisitions to close themselves when they are filled. Hiring now happens through the offer, not through a plain move.

1. salary is an integer > 0. The approval chain depends on the salary: below 100000 ["manager"]; 100000 up to (not including) 150000 ["manager", "director"]; 150000 and above ["manager", "director", "vp"].
2. make_offer needs the application to be at offer and creates an offer with status pending, no approvals and revision 1. An application has at most one offer.
3. approve must be given in chain order: role must be exactly the next role in the chain still missing (anything else, including an unknown role or a repeat, is out of turn). When the last role approves, the status becomes approved; approved lists the roles approved so far.
4. edit_offer (allowed while the offer is pending or approved) replaces the salary, recomputes the chain from the new salary, discards every approval, sets the status back to pending and increases revision by 1. This happens on every successful edit, even when the new salary equals the old one or stays in the same band. A failed edit changes nothing.
5. accept_offer needs an approved offer. It moves the application to hired (offer status accepted).
6. Changed rule: move to hired no longer works; from offer it returns use accept_offer (the check comes after bad transition and before not cleared for offer). Other moves are unchanged.
7. If an application leaves offer by being rejected or withdrawn, its offer becomes void: it can no longer be approved, edited or accepted (not pending / not editable / not approved).
8. Headcount. open_req takes an optional integer headcount (default 1, >= 1). When accept_offer makes the number of hired applications on the requisition reach its headcount, the requisition is closed: every other application on it that is still applied, screen, onsite or offer is moved to rejected with reason "req filled" at the same at, in order of application creation, and their offers become void. accept_offer returns closed (whether this acceptance closed the requisition) and auto_rejected (the candidate ids rejected, in that order). A closed requisition stays closed; apply to it is req closed, checked right after unknown req and before invalid email.
9. Merging (Part 2) must carry offers too: the kept application keeps its offer exactly as it is, and the discarded application's offer disappears with it.

Example (continuing Example 1 of Part 1, where ana is at offer on r1 with headcount 1; bo applied to r1)

[["apply", 600, "r1", "bo", "Bo Chen", "bo@example.com"],
 ["make_offer", 710, "ana", "r1", 120000],
 ["approve", 720, "ana", "r1", "manager"],
 ["edit_offer", 730, "ana", "r1", 120000],
 ["approve", 740, "ana", "r1", "director"],
 ["approve", 750, "ana", "r1", "manager"],
 ["approve", 760, "ana", "r1", "director"],
 ["move", 770, "ana", "r1", "hired"],
 ["accept_offer", 800, "ana", "r1"],
 ["application", 810, "bo", "r1"]]

returns

["applied", [["manager", "director"], 1], ["pending", ["manager"]], [["manager", "director"], 2],
 "error: out of turn", ["pending", ["manager"]], ["approved", ["manager", "director"]],
 "error: use accept_offer", ["hired", true, ["bo"]], ["rejected", "req filled"]]

Notes

• Python 3 standard library only. Everything is deterministic.
• Hidden tests run every Part, so earlier behaviour must keep working after later Parts (except where a rule above says it changed).