Sanctions screening API integration checklist

On this page

Define the decision before connecting the endpoint

A screening integration connects an application to a review process. Define which subjects enter the process, which sources the organization requires, who investigates potential matches, and what happens when screening cannot complete. OFAC’s compliance framework places technology within a wider program of governance, risk assessment, controls, testing, and training.

Keep source selection explicit. Check current coverage, then use named source IDs or an exact versioned package. A broader package is not automatically appropriate for every workflow: financial sanctions, export controls, healthcare exclusions, and reference data have different meanings. The source API documentation explains discovery and selection.

Build one complete synthetic workflow

Use the API quickstart to create a sandbox request with invented subjects. Follow the result into retained history and case review. The public demo helps engineers and reviewers discuss the evidence without exposing customer information.

Synthetic example: a fictional onboarding application submits Mira Calder. A potential_match opens an investigation; a no_match completes the defined list-check step; a coverage or request error leaves that step incomplete. None of these responses should silently become the application’s final customer-acceptance decision.

Implement three outcome paths

Keep the original screening status separate from a later analyst decision. Store the screening reference with your own business record so the same evidence can be located from either system. A reviewer opening an existing retained result does not create a new screening.

potential_match: show the supporting evidence and send the case to the assigned review process.
no_match: retain the selected coverage and versions, then continue only the business process your policy permits.
error: preserve an incomplete state, expose the operational problem to the responsible team, and apply an appropriate retry or escalation path.

Make retries and callbacks safe

Use an Idempotency-Key for a new screening and reuse it only for the same request. If the response is lost after acceptance, retrying that operation can recover its result without adding another completed-screening unit. A changed subject or coverage selection is a new operation. The idempotency guide explains conflicts and retries.

Authenticate webhook signatures using the exact raw body, enforce the timestamp tolerance, and deduplicate event IDs before acting. A repeated notification must not create a second onboarding action. Retrieve result details through authorized access rather than expecting identity inputs in the event. Follow the webhook documentation for the implemented signature contract.

Budget for batches, monitoring, and evidence

A batch acceptance response is not evidence that every row completed. Inspect row-level outcomes, correct failed inputs, and resubmit only the work that needs a new request. Keep failed rows distinct from no-match results. The batch documentation explains progress, uploads, and cancellation.

Monitoring retains a subject for future checks. Each completed rescreen uses the same allowance as other screenings; a daily schedule can consume about 30 screens per subject in a 30-day period before additional source-change rescreens. Select retention settings deliberately and use the pricing allowances to plan the combined volume.

Integration acceptance checklist

Exercise failure paths with synthetic data in an isolated test environment. A success-only demonstration leaves the most consequential integration branches unexplained. Keep request IDs and error codes for diagnosis without logging credentials, submitted subjects, or complete evidence documents.

Verify authentication, least-privilege scopes, revoked keys, and organization access boundaries.
Confirm required source selection and distinguish unavailable coverage from a completed no-match.
Exercise potential matches, no matches, and validation errors through the application’s visible workflow.
Retry an accepted request and verify that the result and usage remain consistent.
Handle repeated webhook deliveries and preserve exactly one intended business action.
Check partial batch failures, cancellation, usage caps, and delayed or stopped monitoring.
Confirm evidence expiry, export access, reviewer responsibility, and a documented recovery path.

Evaluate matching and operate the workflow

Use an independently labeled sample representing the names, scripts, identifiers, and common-name cases relevant to your subjects. Measure missed candidates as well as unnecessary alerts. The name-matching guide explains why a small synthetic check cannot demonstrate accuracy for an entire population.

For production work, use the appropriate production key, available source selection, and plan. Monitor job health, coverage freshness, and allowance consumption. Assign responsibility for failures and relevant source or policy changes. This checklist supports an implementation handoff; it does not certify the organization’s compliance program or replace professional analysis of its obligations.