AML screening API for fintech: a safe integration design

On this page

Be precise about the API’s job

An AML screening API can supply a sanctions or watchlist check inside a broader customer workflow. It does not, by that label alone, provide identity verification, behavioral transaction monitoring, customer-risk assessment, or regulatory reporting. Define each control and its owner.

SanctionsKit’s versioned endpoint is POST /api/v1/screenings. Submit the subject with either explicit supported source IDs or one versioned package. Keep sandbox fixtures separate from production source coverage.

Create the operation before sending the request

Persist an internal operation reference, the exact request body, and a new idempotency key in your backend. Reuse that key only for retries of the same operation and unchanged payload. Keep scoped credentials in server-side secret storage.

A network timeout can happen after the server has accepted the request. Treat the local state as unresolved and retry according to the documented contract; do not generate a new key for every transport retry or mark the customer clear.

Map the response into a deliberate state machine

Validate the response envelope, screening ID, status, and matches collection. A valid no_match describes the selected-source check; potential_match requires the configured review path. Unknown statuses, malformed JSON, and API errors remain incomplete.

Keep customer eligibility outside this parsing function. Your system may need identity verification, external checks, independent approval, or other conditions after a completed sanctions search.

created -> screening_pending
screening_pending -> completed_no_match | review_required | incomplete
review_required -> identity_resolved | escalated
identity_resolved -> separate_business_decision
incomplete -> retry_same_operation | correct_and_create_new_operation

Connect the human decision without changing the evidence

Retained results appear in the organization’s history. Preserve the original outcome and link the investigation, per-candidate decisions, required approvals, and business disposition. Do not automate an analyst approval by inventing an API endpoint that the published contract does not expose.

Use webhook signatures, timestamps, and event IDs according to the webhook documentation. Deduplicate deliveries and persist accepted work before acknowledging it. A webhook acknowledgment does not itself complete the investigation.

Control the ongoing workload

Monitoring retains the subject for later full rescreening against its selected coverage. Plan scheduled and source-triggered activity within the shared production allowance, and define the treatment of quota exhaustion.

Distinguish a short-lived rate limit from a plan usage cap. Respect the specific error response and do not repeatedly retry a cap as though it were a brief outage. Monitoring health belongs in the operational dashboard alongside onboarding completion.

Use a production-readiness test set

Start with the OFAC API guide and the language examples. Run failure scenarios as deliberately as successful requests.

Same body and key replay without creating a new screening operation.
Changed body with an old key raises a conflict rather than silently reusing evidence.
Potential matches and incomplete responses cannot approve a customer.
A valid no-match still waits for other required controls.
Secrets, submitted identity data, and raw evidence stay out of routine logs.