Candidate Pipeline & Messages

This page describes the stages, the rules on moving a candidate, actions on several candidates at once and messages to a candidate. Recruitment is included from the Team plan. This page is part of the reference Recruitment & Hiring.

What It Does

• The stages. Sourced, Screen, Interview, Offer and Hired. A rejected candidate leaves the stages and is kept as Rejected.
• A person always makes the move. The AI match score never moves or rejects anyone.
• Moves that are refused. A candidate with a signed offer can only move to Hired, until the offer is rescinded with a second approver. While an offer is out for signature it has to be withdrawn first, though rejecting the candidate is allowed. Moving a candidate out of Offer or Hired is for people who manage recruitment, and administrators. Moving to Offer needs a completed scorecard; shadow interviews do not count, and administrators are exempt.
• Several candidates at once. You can move, reject, tag or reassign up to 200 candidates in one action. Each is handled on its own, by the same rules as a single action, so some can succeed while others are refused; the result says which.
• Tags, notes and history. Tags are free-text labels for filtering, notes are internal, and the history is the dated record of what happened to the candidate. A person who manages recruitment can export everything held about one candidate, or delete the candidate and their files for good.
• Messages. A message is emailed to the candidate from Zonitix and the thread is kept on their record. If outbound email is not set up, nothing is sent and nothing is stored. On a standard instance a candidate’s reply goes to the mailbox your email is sent from and is not shown in Zonitix.
• Ask AI. A question about your pipeline is answered by the language model that runs on your own instance. Treat the answer as a pointer and check the candidates themselves.

Candidate Pipeline

HR & TalentCandidate Pipeline lists candidates in five stages: “Sourced”, “Screen”, “Interview”, “Offer” and “Hired”. A rejected candidate leaves the stages and is kept as Rejected. Opening a candidate shows the tabs “Overview”, “Interviews”, “Messages”, “Notes” and “History”.

Rules On Moving A Candidate

A person always makes the move; the AI match score never moves or rejects anyone. Four kinds of move are refused:

Working On Several Candidates At Once

Tick candidates in the list and a bar shows how many are selected, with “Move to…”, “Reject”, “Tag…” and “Reassign…”. Each candidate is handled on its own, by the same rules as a single action, so some can succeed while others are refused; the result says which. A candidate already in the target stage, or already rejected, is skipped and gets no second rejection email. One action takes at most 200 candidates. Only a person who manages recruitment can reassign. Each bulk action writes one audit entry with the counts.

Messages To A Candidate

The “Messages” tab emails the candidate from Zonitix and keeps the thread on their record. Enter a “Subject” and a “Message” and click “Send”. People who manage recruitment also see “DRAFT WITH AI:” with “Reject”, “Schedule”, “Nudge” and “Keep warm”, which fill in a draft for you to edit before sending. People who manage recruitment, conduct interviews or source candidates can send; people with read-only access, and final reviewers, can read the thread only.

• Email must be set up. If outbound email (SMTP) is not configured, nothing is sent and nothing is stored, and you see the message Email is not configured, so the message was not sent.
• The candidate needs an email address. Without one the message is refused.
• The thread shows up to 200 messages, oldest first.
• Replies. On a standard instance a candidate’s reply goes to the mailbox your email is sent from and is not shown in Zonitix. Filing replies on the thread needs two settings that have no screen today; they are described under Messages And Replies at the end of this page.

If something here is not working as you expect, start with When something goes wrong.

Routes, Permission Checks And Refusal Codes

Where the sections above say “a person who manages recruitment” or “is refused”, this is the permission that is checked and the answer the API gives. Paths are written as in the API reference.

Candidate Pipeline

Each refused stage move has its own code, so an integration can tell them apart:

• Bulk actions. Reassigning needs manage_recruitment.
• Notes. Read and written by holders of manage_recruitment, conduct_interview or source_candidates. view_recruitment does not include notes.
• Export and deletion of one candidate. manage_recruitment.
• Ask AI. manage_recruitment, view_recruitment or source_candidates.
• Who sees which candidate. An administrator or a holder of manage_recruitment can act on every candidate; everyone else is limited by the rule under Who Sees Which Candidate.

Messages And Replies

Sending a message needs manage_recruitment, conduct_interview or source_candidates; view_recruitment and review_executive_packet can read the thread only. The AI drafts are shown to holders of manage_recruitment. A candidate with no email address answers 400. Sending while outbound email is not configured answers 409 with the code SMTP_OFF.

A candidate’s reply is added to the thread only when an inbound mail address and a shared secret are stored in the instance’s settings (keys recruitment_inbound_email and recruitment_inbound_secret). There is no screen for these two settings today, so on a standard instance replies go to the mailbox your email is sent from and are not shown in Zonitix. When they are set, each message is sent with a reply-to address of the form local+token@domain, and your mail provider posts replies to POST /recruitment/webhooks/inbound-email. The secret travels in the x-inbound-secret header or the JSON body, never in the address. The route is public and rate-limited and always answers 200, so a mail provider does not retry; a call with a wrong or missing secret is ignored and written to the audit log, a reply whose token matches no thread is ignored, and a message id already recorded is not stored twice.

Worked Example: Page Through Candidates

A read with a personal API token, using the same host and token placeholders as the API reference. The token must carry one of manage_recruitment, view_recruitment, source_candidates, schedule_interviews, review_executive_packet or conduct_interview as a scope (a token can only carry permissions its owner holds, and stops carrying one its owner loses), and the list holds only the candidates the owner may see. A token call carries an Authorization header, so it needs no Origin header.