pipeline report agent counted candidates in stages the ATS renamed last quarter - 'Phone Screen' vs 'Intro Call'...

TL;DR

Match candidates on the immutable stage ID, not the display name. Pull the live stage list from the ATS, rebuild your name-to-ID map, and point the report filter at IDs. Stage names are editable labels that admins rename freely; IDs never change. Re-pull the map on a schedule so the next rename is picked up automatically.

The error

Pipeline report counts 0 candidates in "Phone Screen" - the ATS UI shows the same candidates under "Intro Call" after the stage was renamed last quarter

Steps

1. Pull the current stage list for the job from the ATS API and record each stage ID with its current name.

Expected: you see "Intro Call" with a stage ID, and "Phone Screen" is gone from the list.

1. Map every stale name in your report config to the live stage ID in the same position.

Expected: "Phone Screen" resolves to exactly one live stage ID.

1. Change the report filter to match on stage ID, not stage name, and re-run the report.

Expected: report totals match the candidate list in the ATS UI.

1. Add a scheduled refresh that re-pulls the stage map, or subscribe to the ATS stage-change webhook if one exists.

Expected: the next rename updates the map automatically instead of silently breaking the report.

Use this when

• A pipeline report filters, counts, or groups candidates by stage name
• Report numbers disagree with the ATS UI after someone edited stage names
• An agent moves candidates between stages using names from a cached config

Not for this skill when

• Candidates are missing from the ATS entirely (that is data loss, not a rename)
• Counts differ because role permissions hide candidates from the API user
• The job itself was archived or deleted rather than a stage being renamed

Variant phrasings

• ATS renamed stages and my agent's reports broke
• candidates counted in the wrong stage after a stage rename
• "Phone Screen" vs "Intro Call" stage name mismatch in pipeline reports
• agent moved candidates to a stage that no longer exists by name

Why it happens

ATS stages have immutable IDs and editable display names. The agent treated the display name as the key, so when an admin renamed "Phone Screen" to "Intro Call", every filter built on the old name matched nothing while the candidates sat under the new name. Name-based matching is brittle by design; the ID is the stable identifier.

Edge cases

• Historical snapshots keep the old name, so label archived reports with the stage-map version used.
• Two jobs can share stage names: always scope the map per job ID, never globally.
• Stage order can change without a rename: if the agent depends on position, re-pull ordering too.
• Archived stages still hold candidates: exclude archived stage IDs from active-pipeline counts explicitly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_KKPJo-G1DVQI4SnsIjCjkw