Fintech AML screening API integration: requests, results and review

Create a key for a synthetic first check

This guide implements one part of AML onboarding: sanctions screening with SanctionsKit. In API keys, create a Sandbox key with screenings:write and results:read. Add sources:read for later Production discovery. Store SANCTIONSKIT_API_KEY in server-side configuration.

The example uses a fictional customer and synthetic coverage. It tests the request and review flow. Identity verification, ownership work, transaction monitoring and regulatory reporting still need their own processes.

Submit one customer party and preserve the request

POST /api/v1/screenings requires an Idempotency-Key. Create REQUEST_KEY once for the intended check and store it with the exact body. Reuse both after a timeout. Use a new key when corrected identity details or a later check calls for new work.

Run the example from an development environment you are allowed to use with your Sandbox secret. The reference connects the result to your merchant-party record; it is not a name used for matching. Standard retention lets analysts review the result in the dashboard.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/screenings" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_KEY" \
  --data '{
  "subject": {
    "name": "Alex Morgan",
    "entityType": "person",
    "birthDate": "1984"
  },
  "package": "sandbox@1",
  "reference": "demo-merchant-1042-representative",
  "retention": "standard"
}'

Map a successful result to the next step

Read data.id, data.status, data.matches and data.coverage after success. Store the result ID and coverage versions with your party reference. A potential_match needs identity review. A no_match completes only this selected-source comparison.

An HTTP error, unknown status or malformed response is incomplete. Repair credentials for 401 or 403 errors. A 503 coverage failure must not cause your app to drop a source and approve. Handle rate_limited separately from usage_cap_reached, following error guidance. 

Connect the developer result with analyst work

Find the result in Screening history and its candidate case in the Review queue. The analyst records identity findings, external checks and the business decision. An API key cannot stand in for a human approver.

GET /api/v1/results/{id} wraps the saved result in data. GET /api/v1/results/{id}/evidence returns the evidence JSON itself. Keep the original outcome separate from later decisions. For screening.completed webhooks, verify signatures and deduplicate event IDs. A delivery acknowledgment is not review completion.

Replace synthetic coverage with approved sources

With an authorized Production key, call GET /api/v1/sources. Confirm every required source is available and supports the subject type. Replace package: sandbox@1 with the approved sources array or another available exact package version. Never send both selectors.

Read GET /api/v1/policies when policy is required, then send policy: { id, version } with permitted coverage. Keep standard retention so the dashboard team can review it. Test candidates, no-matches and unavailable coverage before connecting the response to live onboarding. The Node.js integration provides a full client example.

Handle changed identities and later checks

Use POST /api/v1/monitors or Monitoring for approved continuing subjects. Follow the monitoring reference for request fields and update concurrency. Assign review work and plan for the shared allowance.

Updating a saved counterparty does not rewrite past results. Linked monitors pause for identity reconciliation. Confirm the new subject and policy before resuming, so later checks do not keep using the original onboarding details by accident.

Frequently asked questions