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 questionThe signalWhat it meansWhat 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

StatusFinal?MeaningWhat to do
PENDINGNoCreated, not yet started.Wait.
RUNNINGNoExecuting. A hosted check may be waiting on the subject.Store the IDs and wait. Do not decide yet.
COMPLETEDYesIt ran and returned a result.Evaluate the outcome, risk and flags.
FAILEDYesIt 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.
SKIPPEDYesNot run, typically because a prerequisite check did not pass.Treat as no result, not a negative one.
CANCELLEDYesStopped before it ran.Treat as no result.

Completed is not the same as clear

A completed check carries one of several outcomes:

SignalInterpretation
Outcome CLEAR, usually riskLevel: "LOW"The result cleared the check.
Outcome REVIEW, or elevated risk and flagsA result exists and needs a human or policy decision.
Outcome FLAGGED, or HIGH / CRITICAL riskA 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

StateFinal?Meaning
PROCESSINGNoAt least one check is still pending, running, or waiting on the subject.
report.readyYesThe report finished its lifecycle. Inspect every entry in checks — they can be clear, review, flagged or partial.
report.failedYesThe 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.

  • Webhooks — the payloads these statuses arrive in
  • Errors — HTTP failures, which are a different thing again

On this page