Statuses and outcomes
What success, pending and failure each mean — and which one you are looking at.
There are three different kinds of success in a Verifisha integration, and they are not interchangeable. Most integration bugs come from treating one as another.
| The question | The signal | What it means | What it does not mean |
|---|---|---|---|
| Did my endpoint receive the delivery? | Your endpoint returned any 2xx. | Verifisha records the delivery as successful. | Anything at all about the result. |
| Did a check finish running? | status: "COMPLETED" with lifecycle.terminal: true. | Execution finished and a result exists. | That the subject was cleared. |
| Did the result clear my policy? | COMPLETED, plus an outcome, riskLevel, riskScore and flags you accept. | The result meets the policy you chose. | That the rest of the report has finished. |
| Is the whole report final? | report.ready or report.failed, with lifecycle.terminal: true. | No further processing for that report. | That every check cleared. |
The clearance decision is always yours. Verifisha reports what it found; your policy decides what to do about it.
Check statuses
| Status | Final? | Meaning | What to do |
|---|---|---|---|
PENDING | No | Created, not yet started. | Wait. |
RUNNING | No | Executing. A hosted check may be waiting on the subject. | Store the IDs and wait. Do not decide yet. |
COMPLETED | Yes | It ran and returned a result. | Evaluate the outcome, risk and flags. |
FAILED | Yes | It could not complete — an expired session, a lookup that did not return. | Retry, or start a new session. Never record it as an adverse finding. |
SKIPPED | Yes | Not run, typically because a prerequisite check did not pass. | Treat as no result, not a negative one. |
CANCELLED | Yes | Stopped before it ran. | Treat as no result. |
Completed is not the same as clear
A completed check carries one of several outcomes:
| Signal | Interpretation |
|---|---|
Outcome CLEAR, usually riskLevel: "LOW" | The result cleared the check. |
Outcome REVIEW, or elevated risk and flags | A result exists and needs a human or policy decision. |
Outcome FLAGGED, or HIGH / CRITICAL risk | A result exists and contains material risk. Apply your escalation policy. |
status: "FAILED" | No conclusion was reached at all. Not clear, not review, not flagged. |
A check that finds a sanctions match is COMPLETED. So is one that matches
nothing. If your code treats COMPLETED as approval, it will approve the
sanctions match.
Where to read the outcome
Sandbox payloads expose it directly as checks[].outcome. Production webhooks
carry it inside the evidence — the checks[].evidenceDetails entry whose key
is outcome, with values such as Clear, Review or Flagged.
Read it together with riskLevel, riskScore and flags rather than on its
own.
Report statuses
| State | Final? | Meaning |
|---|---|---|
PROCESSING | No | At least one check is still pending, running, or waiting on the subject. |
report.ready | Yes | The report finished its lifecycle. Inspect every entry in checks — they can be clear, review, flagged or partial. |
report.failed | Yes | The report could not reach a usable state. Checks that finished before the failure may still be included. |
The report status itself differs by environment — sandbox reports complete as
READY, production reports as COMPLETED. The portable signal is
lifecycle.terminal: true together with report.ready or report.failed.
Branch on those, not on the status string, and your code will behave the same
in both.
Deciding in code
if (!payload.lifecycle.terminal) return // progress only, wait
if (event === "check.failed") retryOrReissue() // no finding, not a decline
if (event === "report.failed") escalateToOps() // nothing usable
if (event === "report.ready") {
for (check of payload.checks) {
if (check.status !== "COMPLETED") continue // skipped, cancelled, failed
applyPolicy(check.riskLevel, check.riskScore, check.flags)
}
}The only states that warrant a business decision are the terminal ones with a
COMPLETED check behind them. Everything else is either progress, or an
operational problem to retry.