A screening API result is not a decision record. Here is what it must return.

Most API evaluations begin with two questions: “Can it find a name?” and “How fast is it?” Both matter. Neither tells an engineering or compliance team whether it can defend the decision made after the response arrived.

An API can return clear, match, possible_match or a similarity score. Those fields may be useful workflow signals. But they are not, by themselves, evidence of what was checked, why a candidate appeared, which information was missing or who accepted the risk. If a response cannot be explained later, the integration has created a brittle control no matter how elegant the endpoint looks.

Short answer

An auditable screening API must return more than a verdict. At minimum, it needs enough information to reconstruct the query, identify the data/source state, inspect returned candidates, understand why each candidate was retrieved, record the human or rule-based disposition, and retrieve the immutable evidence for the decision. The API should distinguish clearly between candidate retrieval, risk signal and final case decision.

The minimum response contract

The key word is distinguish. A system that uses one status field for all six layers forces every downstream integrator to guess what it means.

Candidate retrieval is not confirmation

Name matching is probabilistic. An exact name may identify the wrong person; a fuzzy or phonetic match may be the right person but need more identifiers. So an API’s first job is often to retrieve a candidate set worth reviewing. The API should show the reasoning supporting that retrieval without pretending that a score is legal or factual certainty.

For example, an integration may receive three candidates. The useful response tells the analyst which names, dates of birth, nationalities, registration IDs or aliases aligned; which fields conflicted; and which record/source supplied those attributes. “Confidence 82” communicates less than a short explanation plus evidence.

Source freshness belongs in the response

Teams routinely ask, “Which lists do you cover?” The stronger question is, “Which source state contributed to this result?” A broad coverage page can be current today and wrong for a record screened last quarter. A transient ingestion issue can matter to one workflow even when the API is otherwise healthy.

For that reason, a response or retrievable evidence object should carry the relevant source state at screening time. That does not mean dumping a huge internal pipeline log into every API call. It means preserving a clear statement of the consulted sources, their status, their timestamp/version and any material limitation. The Verifex Sources & Freshness model is useful precisely because it makes freshness a first-class fact rather than a footnote.

Design the integration around a case lifecycle

A reliable integration should have at least four states:

1. Screened: the API received the subject and returned data/source context plus candidates.
2. Triaged: a rule or reviewer decided whether more information was needed.
3. Disposed: a person or approved workflow cleared, escalated, rejected or deferred the case, with a reason.
4. Reopened: a source update, ownership change or new information caused a later review without deleting the earlier decision.

This lifecycle avoids a common implementation failure: automatically treating a synchronous 200 OK response as permission to onboard, pay or ship. Success at the HTTP layer says the request completed; it does not say the counterparty is safe.

Questions engineers should ask during a vendor evaluation

• Can we retrieve the original screening evidence after retention periods or user-interface changes?
• Does every response have a stable correlation ID and a documented replay/idempotency model?
• Can the reviewer see why a candidate was returned, not just the vendor’s summary label?
• Can source freshness and exclusions be surfaced to the customer’s own policy engine?
• Are manual decisions and overrides captured through the API or only inside a dashboard?
• What happens if a source is stale, unavailable or intentionally excluded from a workflow?
• Can we export a case without a manual screenshot exercise?

The answers are architectural. They should appear in product documentation and test cases, not be discovered during an audit.

Where Verifex fits

Verifex is built around evidence-preserving screening workflows: source context, candidate reasoning, review state and an Evidence Capsule should remain associated with the case. Engineers should validate the exact response fields, source scope, retention behaviour and integration semantics in the current documentation before implementation. The point is not to promise an automatic clearance; it is to ensure that a team can explain the decision it made.

Sources and further reading

• Verifex: developer documentation
• Verifex: matching methodology
• Verifex: Evidence Capsule
• NIST: Guide to Integrating Forensic Techniques into Incident Response — useful general principles for preserving evidence and chronology