Sanctions screening API integration: a rollout checklist

Set up a sandbox key and define the task

Create a Sandbox key in API keys. Grant screenings:write to submit, results:read to retrieve saved results and sources:read for source and policy discovery. Store it in backend secret settings. Use the quickstart or a language guide. The base URL is https://www.sanctionskit.com/api/v1.

Before coding the success path, agree which parties enter screening, which sources are required and who reviews possible matches. Define what happens when a check cannot finish. The technology supports a wider process of risk assessment, controls, testing and training; a working API request does not replace it.

Keep source selection explicit. Check coverage, then save a versioned policy with required sources by subject type, outside checks and approval rules. Where settings permit, a request can use named sources or an exact package version. Financial sanctions, trade lists and healthcare exclusions answer different questions. Use the source API guide to select the scope deliberately.

Follow a result into the review process

Send an invented subject through the API quickstart. Find the saved result and its review case. Use the public demo to discuss the evidence with analysts without exposing real customers. Agree which system stores the business reference and how a reviewer gets back to it.

For a fictional onboarding request for Mira Calder, potential_match starts identity review. no_match completes the defined list-check step. A coverage or request error leaves that step incomplete. Your application still needs a separate rule for whether the overall customer task is ready to proceed.

Build three clear result paths

Keep the original screening outcome separate from a later analyst decision. Save the screening reference with the business record so both teams can find the same evidence. Opening an existing saved result does not run a new check. The table below gives each result or failure a distinct next step.

• potential_match: show the supporting evidence and send the case to the assigned review process.
• no_match: retain the selected coverage and policy version, complete any wider required checks, and record the business disposition in a due-diligence case when your process requires one.
• error: preserve an incomplete state, expose the operational problem to the responsible team, and apply an appropriate retry or escalation path.

Make retries and webhook handling safe

Use an Idempotency-Key for each new check. Reuse it only with the same request. If a response is lost after acceptance, a retry can recover the result without another completed-screening unit. Changed subjects or sources need a new operation. The idempotency guide covers retries and conflicts.

Verify webhook signatures against the exact raw body, check the timestamp tolerance and deduplicate event IDs. A repeat notification must not cause the same onboarding action twice. Retrieve result details with authorized access; do not expect the event to contain identity inputs. Use the webhook guide for the signature format.

Plan for batches, repeat checks and retention

A batch accepted for processing does not mean every row completed. Read each outcome, fix failed inputs and submit only the work that needs a new request. A failed row is not a no-match. The batch guide explains uploads, progress and cancellation.

A monitor saves a subject for future checks. Each completed rescreen uses the same allowance as other screenings. Daily checks can mean about 30 screens per subject in a 30-day month, before extra source-change rescreens. Choose retention and use pricing allowances to plan the total, not just the initial import.

Test the points where the process can stop

Use synthetic data in an isolated test environment. Cover failed requests, uncertain responses and cases awaiting people, as well as success. Keep safe request IDs and error codes for diagnosis. Do not log keys, submitted subjects or full evidence documents. The checklist below helps record what your test actually proved.

• 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 retention triggers, selective hold release, export access, independent approval, and a documented recovery path.

Check Production access and ongoing ownership

Create a separate Production key. A request header cannot change its environment. With sources:read, call GET /api/v1/sources and verify source availability and supported subject types. Replace sandbox@1 with the intended sources or package. Include the exact published policy reference and its required coverage when it applies. Check access and allowance in Billing & invoices and Usage & limits.

Use independently labeled cases that reflect the names, scripts, IDs and common names you expect. Count missed candidates and extra alerts. The name-matching guide explains why a few synthetic examples cannot prove accuracy for every customer population.

Assign an owner for failed jobs, stale coverage, usage limits and relevant source or policy changes. Verify required outside dependencies before treating them as ready. This checklist helps teams hand over an integration. It does not certify the organization's program or decide its legal obligations.

Frequently asked questions