Ref-22251 · Candidate background check

The states of GetCandidateBackgroundCheckHttp

GET /get-candidate-background-check is the single endpoint behind the unified candidate page at /candidate-portal/background-check/:accessId. Given only an access code it resolves which of five states the candidate sees. This page documents those states, the four package flows that reach them, and — the part that matters most — which states are protected by a valid session cookie or by live eID verification.

Resolution

One route, one builder, five states

The candidate link (and the deprecated identification / review / review-callback / review-identity-gate links, now 301 redirects) all land on the same page. It calls the endpoint, whose handler runs buildCandidateBackgroundCheckResultGated to derive the state from the stored background-check status, the package's gates, and the presence of a valid session cookie.

GetCandidateBackgroundCheckHttp Current
State machine

CandidateBackgroundCheckResult — 5 states

not-found
No active BGC entry at this access code, or the current status isn't candidate-actionable.
404 page
identity-collection-required
BGC ordered, awaiting the candidate's identity submission. Also the fallback when a gated outcome is requested without a valid cookie.
SubmitIdentificationPage
report-review-required
Candidate must pass live eID verification to view or approve the completed report.
IdentityVerificationGate
report-ready
Approval-no-gate flow: candidate approves directly inside the BGC app.
JS redirect + JWT
submitted
Flow complete. Outcome: verified, declined, proceeded-unverified, approved, or report-declined.
EndOfFlow
Candidate experience

The 4 package flows

identity-collection
legalChecks
Candidate verifies (or declines) their identity with an eID. On completion a session cookie is minted and the check runs. Enters submitted (verified / declined / proceeded-unverified).
identity-collection-required → eID → submitted
report-approval
legalChecks requiresCandidateApproval
Candidate verifies eID to view the completed report, then approves sharing it. Enters submitted (approved).
report-review-required → eID verified → submitted (approved)
approval-no-gate
requiresCandidateApproval legalChecks
No Refapp eID gate. Builder returns report-ready and the page redirects the candidate to the BGC app with a JWT to approve there. The BGC app calls back to the unified route with ?token=….
report-ready → JS redirect → approve in BGC app → submitted (approved)
report-appendix-gate
onlyCandidateCanSeeSensitiveData
OCSSD (GDPR Art. 10): the completed BGC has a sensitive appendix. Candidate verifies eID to unlock the report view. Takes precedence over the other flags.
report-review-required → eID verified → view sensitive appendix
Access control

Which states require eID verification (valid cookie)

Two independent gates protect candidate outcomes. Cookie gate — buildCandidateBackgroundCheckResultGated hides a finished Flow-A outcome unless the caller presents a valid session cookie, so holding the access-code URL alone never reveals the result. eID gate — report-review-required demands a fresh eID verification before the report can be viewed or approved.

State / outcome Valid session cookie Live eID verification Notes
not-found n/a n/a Nothing to reveal.
identity-collection-required no not yet The pre-verification state itself. The candidate submits their identity here (which mints the cookie).
report-review-required no required legalChecks or OCSSD gate. Candidate re-verifies via SubmitBackgroundCheckReportReviewVerifiedIdentityHttp before seeing the report.
report-ready no no approval-no-gate: JWT redirect to approve inside the BGC app.
submitted · verified required done earlier Cookie-gated when status ∈ collection statuses; without a valid cookie it downgrades to identity-collection-required. Exception: a verified outcome reached from completed-ok/completed-anomalies is not gated (the candidate may never have done identity collection).
submitted · proceeded-unverified required no Candidate declared a country instead of verifying. Cookie-gated; without it → identity-collection-required.
submitted · declined required n/a Status candidate-declined. Cookie-gated; without it → identity-collection-required.
submitted · approved no done earlier Flow-B terminal. Any eID gate already happened at report-review; the terminal itself is not cookie-gated.
submitted · report-declined no n/a Flow-B terminal (status candidate-review-declined). Not cookie-gated.
cookie-gated — hidden without a valid session cookie, shown as identity-collection-required instead eID required — a fresh eID verification is needed to proceed
The session cookie. bgc_candidate_session — HttpOnly, SameSite=Lax, path /, 24-hour lifetime. Minted (mintCandidateSession) when the candidate finishes identity collection — verified, declined, or proceeded-unverified — and validated on later requests by getHasValidSession (SHA-256 token hash compared against the value stored on the entry). Only the collection statuses ordered, in-process, partial-completed-ok, partial-completed-anomalies, and candidate-declined are subject to the cookie gate.