Status mapping overview

When Selection Lab processes an assessment, the outcome (pass, fail, incomplete, abandoned, or proctoring-failed) must translate into a visible ATS state before any downstream action can occur. Without a deterministic mapping layer, two problems emerge: recruiters either manually intervene on every result, or automated rules fire incorrectly and disqualify candidates who simply ran into a technical issue.

Four terms define the system:

• Status mapping is the configured rule that translates an assessment outcome category into a specific ATS stage or status value.
• Rejection flow is the execution path triggered when an outcome maps to a disqualified/rejected stage, including any candidate notification and pipeline closure.
• Automated invitation is the downstream action (send interview invite, suppress invite, or notify recruiter) that fires once the ATS stage has been updated.
• Sync direction distinguishes the two legs: ATS-to-partner for order creation and invite delivery; partner-to-ATS for results and status pushes.

One distinction matters above all others: incomplete is not fail. A candidate who abandoned the session, lost connectivity, or triggered a proctoring hold has not failed the assessment. Mapping incomplete directly to a rejected stage causes false negatives and erodes recruiter trust. Always route incomplete outcomes to a separate "needs action" or "in review" stage pending human review or re-invite.

The end-to-end flow is:

Intake / Order created
  → Candidate receives assessment access
    → Outcome computed (pass / fail / incomplete)
      → Outcome mapped to ATS stage/status
        → ATS stage updated via API or webhook
          → ATS automation fires (invite / suppress / notify)

Default mappings used by Selection Lab

Selection Lab automates recruitment decisions up to the interview stage, surfacing assessment results directly in the ATS while keeping the candidate experience conversational (via SmartChat, which responds within 10 seconds across WhatsApp and webchat). The default status mapping table below reflects that operational model.

For a standard pipeline (apply → phone_screen → interview → evaluation → hire), fail maps to disqualified and blocks all further invitation triggers. incomplete maps to needs_action rather than disqualified, ensuring a recruiter can decide whether to re-invite or close the application. This conservative default is what keeps Selection Lab's drop-off rate 27% lower than unmanaged flows (Selection Lab Main Deck 2026, March 2025).

How to customize mappings per job

Default mappings apply at the account level but can be overridden per job, per offer, and per assessment package. This matters because rejection policy differs across roles: high-volume warehouse hiring may accept automated rejection on fail, while a legal role may require every completed result to reach a recruiter before any stage change fires.

Configuration granularity covers two axes:

1. Outcome-to-stage mapping: which ATS stage or status value each outcome category resolves to.
2. Invitation policy: whether passing the mapped stage triggers an automated invite, suppresses it, or routes it to a recruiter inbox.

A policy matrix covering the three common patterns:

Changing a mapping after candidates have already been processed does not retroactively re-run their status. The system writes a no-op audit entry for any candidate whose (candidateId, jobId, orderId) tuple already has a recorded mapping outcome. To re-run a specific candidate through the updated mapping, an explicit re-process request is required, which generates a new audit record rather than overwriting the original.

Webhook and API payload examples

Recruitee

Recruitee webhooks are configured under Settings > Apps and Plugins > Webhooks. Your endpoint must use HTTPS, and the configuration is only "Verified and created" after your service responds with HTTP 200 to the initial test request. The "Manage webhooks" hiring role ability must be enabled for the configuring user.

Each webhook event object carries the following fields:

{
  "id": "evt_01abc23def",
  "attempt_count": 1,
  "created_at": "2026-08-29T10:00:00Z",
  "event_type": "candidate_moved",
  "event_subtype": "disqualified",
  "payload": {
    "candidate_id": "cand_99887766",
    "job_id": "job_11223344",
    "details": {
      "to_stage": "disqualified",
      "disqualify_reason": "Assessment score below threshold"
    }
  }
}

For a stage advance (pass mapped to interview), the event_subtype is stage_changed and payload.details contains both from_stage and to_stage. For a rejection, event_subtype is disqualified and payload.details carries to_stage plus disqualify_reason. The requalified subtype reverses a prior disqualification, which is relevant if a manual review overrides an automated rejection.

Verify every incoming event by computing an HMAC-SHA256 digest of the raw request body using your configured webhook secret and comparing it to the X-Recruitee-Signature header value (base16/hex encoded). Reject events with a mismatched signature by returning a non-200 status so the failure is recorded in Recruitee's delivery logs.

SmartRecruiters

SmartRecruiters assessment partner integration follows an OAuth-based lifecycle: after credential exchange, the partner receives order creation callbacks when a candidate reaches the assessment stage. Selection Lab sends assessment results back via a PATCH to the order's status endpoint, updating the result object with fields including status (e.g., COMPLETED, FAILED), score, and completedAt. The ATS then processes the callback and advances or holds the candidate's pipeline stage based on its own automation rules, which should align with the stage mappings configured for that job.

Always propagate orderId, packageId, and Selection Lab's internal assessmentSessionId as correlation identifiers in both directions. This ensures that if a callback fails and retries, the receiving end can check the (candidateId, orderId) tuple and skip reprocessing if the stage update already applied.

Error handling and retry logic

Three failure classes require distinct handling:

1. Delivery failure: the webhook endpoint did not return HTTP 200 within the timeout window.
2. API failure: the ATS partner API returned a 4xx or 5xx response to a status update request.
3. Semantic failure: the payload arrived but contains missing scores, an abandoned session, or a proctoring hold that prevents a definitive pass/fail determination.

For Recruitee, any response status other than 200 counts as a delivery failure. Recruitee retries up to nine times on the following schedule (from the Recruitee Webhooks documentation):

Each retry carries the same id and increments attempt_count. Your handler must be idempotent: check (candidateId, jobId, orderId) before applying any stage change or invitation action. Every request is logged for 30 days; logs include the request body, response, next scheduled attempt, and options to cancel automatic retry or trigger an immediate retry manually.

Rate limits: trial Recruitee accounts are capped at 5 webhook requests per minute; all other accounts at 100 per minute. When the limit is reached, further webhook requests are delayed by approximately 10 ± 5 minutes.

For SmartRecruiters, callback delivery success is determined by HTTP 2xx responses within the platform's timeout window. Treat all non-2xx responses as retriable, and implement the same idempotency check on orderId before re-applying any status update.

For semantic failures, do not map an abandoned or proctoring_failed outcome to disqualified without explicit recruiter confirmation. Route to needs_action and surface the assessmentSessionId in the ATS notes field so the recruiter has full context.

Examples: reject-on-fail and notify-on-complete

Example A: reject-on-fail

Job-level mapping: fail → disqualified; pass → interview; incomplete → needs_action.

1. Candidate completes the Selection Lab assessment.
2. Selection Lab computes RESULT_FAIL and pushes a stage-change request to Recruitee (or a PATCH to SmartRecruiters order endpoint) with to_stage: disqualified and disqualify_reason: "Assessment score below threshold".
3. The ATS fires its configured automation for the disqualified stage (rejection email, pipeline close). No interview invite is issued.
4. If the PATCH returns a non-200, Selection Lab queues a retry. On each retry, the handler checks whether (candidateId, jobId, orderId) already maps to disqualified; if yes, it returns 200 immediately without rewriting the stage (preventing duplicate notification emails).
5. The attempt_count in the Recruitee event object increments with each delivery attempt, which your logs can use to detect systemic endpoint issues.

Example B: notify-on-complete

Job-level mapping: pass → interview (invite sent); fail → evaluation (report stored, no invite, no auto-disqualify); incomplete → needs_action.

1. Candidate completes the assessment. Selection Lab pushes the full report to the ATS regardless of outcome.
2. For pass: the ATS advances the candidate to the interview stage and fires the interview invite automation.
3. For fail: the candidate stays in the evaluation stage. The recruiter reviews the report and decides whether to close or consider the candidate for a different role. No rejection stage is written automatically.
4. For incomplete: the candidate moves to needs_action. After a configurable hold period (e.g., 48 hours), if the recruiter has not acted, Selection Lab can send a single re-invite. A re-invite counter per (candidateId, orderId) prevents loops; the default maximum is one re-invite, after which the record escalates to manual review only.

This pattern aligns with policies that prohibit automated rejection without human sign-off, and it keeps the pipeline clean without requiring recruiters to process every failed result immediately.

Frequently asked questions about ATS status mapping