Skip to content
Developers
Back to Steward

Screening

A screening hit is a potential match against an application’s entities: a sanctions listing, PEP (politically exposed person) record, adverse-media article, or watchlist warning. Your team reviews each hit and records a decision.

Hit types and statuses

Section titled “Hit types and statuses”
type Match against
SANCTIONS Sanctions lists
PEP Politically exposed persons
ADVERSE_MEDIA Negative news / media
WARNING Watchlist and other warnings

A hit’s review status moves through the values below. New hits start NOT_REVIEWED.

status Meaning
NOT_REVIEWED Awaiting review (default)
IN_REVIEW Under review
TRUE_MATCH / CONFIRMED Confirmed as a real match
FALSE_POSITIVE / DISMISSED Determined not to be a match

Working with hits

Section titled “Working with hits”
  • GET /screening/hits?applicationId=… returns the application’s hits grouped into sanctions, pep, adverseMedia, and warning arrays.
  • PATCH /screening/hits/{hitId} records a review decision: the new status, an optional note, and an optional severity tier. Updating a hit re-triggers risk calculation.
  • POST /screening/hits creates a manual hit (a match your team adds directly rather than one surfaced by a provider) from a title, type, status, and optional source details.

The screening/individuals/{id} and screening/businesses/{id} endpoints (and their /summary variants) let you correct the screened entity’s details or record a written summary.

Bulk verdicts

Section titled “Bulk verdicts”

POST /screening/bulk/hit-verdict applies one status, optional note, and optional severity to selected hitIds. POST /screening/bulk/group-verdict applies those fields to selected groupIds, with each group verdict covering all of its member hits. Responses separate changed and skipped ids using the matching resource names and include changedCount and skippedCount. POST /screening/bulk/story-verdict is a deprecated compatibility alias for the group route; it accepts storyIds and returns story-named response fields.

Each request must contain between 1 and 500 valid id entries. The 500-entry limit is checked before repeated ids are coalesced in request order. Steward checks the complete selection before writing: missing ids return 404 with the missing ids, ids outside the API key’s account return a generic 403, and Steward-hidden applications return 404. Group requests also check every constituent hit. Nothing is written when this selection check fails.

A hit changes when its status, supplied note, or supplied severity differs. A group changes when any member status differs, the supplied severity differs from the group or a member, the supplied rationale is not already recorded, or a pending reconciliation remains. Exact no-ops skip writes, notes, events, task changes, and risk recomputation. Effective changes preserve the single-hit or single-group event, rationale, task, and risk behavior. A group still applies its member verdict atomically, but the bulk request does not promise one database transaction across all selected groups or downstream side effects.

Deciding a whole group at once

Section titled “Deciding a whole group at once”

The same underlying subject often surfaces across several sources. Steward collects those into a screening group so one verdict can settle all of them.

PATCH /screening/groups/{groupId} sets a verdict (the same status values as a single hit, plus one shared note and an optional severity) and applies it to every source hit under that group. Use it when one decision genuinely covers them all; use PATCH /screening/hits/{hitId} when the hits need separate verdicts.

Note: PATCH /screening/stories/{storyId} is a deprecated alias for this endpoint, kept for compatibility. It behaves identically. Use /screening/groups/{groupId} in new integrations.

Example

Section titled “Example”
Terminal window
# List an application's hits, grouped by type
curl "https://api.getsteward.ai/api/v1/screening/hits?applicationId={id}" \
  -H "Authorization: Bearer stw_live_your_api_key_here"


# Record a review decision on a hit
curl -X PATCH https://api.getsteward.ai/api/v1/screening/hits/{hitId} \
  -H "Authorization: Bearer stw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "FALSE_POSITIVE", "note": "Different date of birth" }'