Sanctions screening testing: build useful acceptance cases

Test the whole handoff, from request to reviewer

Sanctions screening testing should show that your application can submit a check, find its result and route the next task correctly. Use SanctionsKit's synthetic Sandbox to rehearse that flow. Include a failed request so a missing result cannot accidentally approve a customer.

Start with the API quickstart, a server-side sandbox key and invented subjects. Keep keys and submitted subjects out of logs. Your harness can record the request shape, operation key and safe result reference. A sandbox pass does not prove live source accuracy or freshness.

Check a real authenticated request and its saved evidence

Send the synthetic JSON body below to POST /api/v1/screenings with Authorization: Bearer and a stored Idempotency-Key. Expect HTTP 201 and a ScreeningResult inside data. Validate data.id, data.status, data.coverage, data.matches and data.versions before using the result.

With results:read, retrieve GET /api/v1/results/{id} and its evidence download. Test their formats separately: the result is data-wrapped; the evidence is a raw sanctionskit-evidence@1 document. A parsing or retrieval failure should leave the task pending, not create an empty successful result.

{
  "subject": {
    "name": "Alex Morgan",
    "entityType": "person",
    "birthDate": "1984"
  },
  "package": "sandbox@1",
  "retention": "standard"
}

Make failures and retries part of acceptance

Test wrong credentials or scopes, invalid subjects, both coverage selectors together, missing required sources, timeouts and rate limits. Keep every error distinct from no_match. An unknown error code is still a failure. Never substitute an empty matches array for a missing response.

After an uncertain response, retry the identical request with its original Idempotency-Key. Verify that the application does not generate a new key on every attempt. Changed intended work needs a new key. Use the error guide and retry guide for the exact behavior.

Complete the analyst and approval path

Open a retained synthetic candidate in Review queue. Have a permitted reviewer compare facts, record identity and business decisions, finish outside checks and submit. Where required, use another eligible person for approval and test that self-approval is rejected.

Read the case through the API and check how your application treats submitted, approved, escalated, reopened and replaced work. API keys must not act as human reviewers. Also try a no-match whose policy still requires outside due diligence, so the list result cannot close unfinished work.

Test monitoring and delivery as separate steps

Create a monitor and confirm that active does not mean its first check finished. Read /api/v1/monitoring until there is a successful result or visible issue. Exercise changed subjects, pauses, resumed work and inbox reads. Acknowledging an event must not close the linked case.

For webhooks, test raw-byte signatures, timestamp tolerance, duplicates and recovery after durable storage. Follow the webhook guide. If a failure cannot safely be induced, simulate it in your own harness and label that test as a local simulation.

Report what each test actually establishes

Save the fixture version, application build, expected outcome and observed result. Distinguish an authenticated request from a mocked response. Keep Sandbox behavior separate from verified Production source access and permissions. A test report should make untested dependencies obvious.

For matching changes, test known positive and negative cases under both profiles. Record misses as well as queue size. Use the profile guide for supported controls. A small synthetic set cannot support a worldwide matching-accuracy claim.

Define expectations before running the matcher

Derive labels from the fixture facts, not the current engine output. For an invented source entry, state which identity and variants should be found and which comparisons remain uncertain. Explain why. Otherwise a test can repeat an existing mistake and still pass.

Use one set for development and a separate set to evaluate changes. Include scripts, partial dates, similar companies and identifier schemes relevant to your users. State where the set is narrow. A few English names cannot establish quality for every language or customer population.

Frequently asked questions