AML Screening API Integration Without Slowing Onboarding

The integrations that feel slow are the ones that treat screening as a separate back-office job. The customer finishes KYC, the account sits in limbo, and someone in compliance pastes a name into a portal. The integrations that stay out of the way treat screening as a decision service: you already have a legal name, you call the API, you persist the id, and the product knows what to do with AUTO_CLEAR, REVIEW, and CONFIRMED.

Connect Naiza to the identity collected during onboarding. Once the legal name and a stable externalId are available, call screening from your server and store the result on the customer record.

What to send, and when

Collect the legal name and your own externalId before you call POST /api/v1/aml/screen. Add date of birth, nationality, aliases, and document identifiers when you have them. Optional fields improve matching. They do not replace the KYC file, and they do not need to block the first screen if KYC is still fetching a secondary document.

I mint externalId in our customer service, not in the AML vendor. If the screen times out, I still have a key I can join later. If KYC retries, I reuse the same id so I do not create a second customer that never inherits the first case.

POST /api/v1/aml/screen
x-api-key: naiza_api_sk_live_...

{
  "inputName": "John Michael Smith",
  "externalId": "cust_123456",
  "entityType": "INDIVIDUAL",
  "inputDob": "1985-04-12"
}

Persist the returned screening id on the customer or onboarding record. Support and compliance will ask for it. If you only log it in an application table that expires in two weeks, you will rebuild the case from memory.

How the three outcomes should feel in the product

AUTO_CLEAR is the low-friction path. If the rest of onboarding is done, activate. Do not invent a second waiting room for a clean screen. That is how you train customers to think screening is a delay even when it is not.

REVIEW routes a potential match to investigation. Hold activation or payout according to your workflow, open a case with the input fields and screening id, and compare the supporting identity evidence.

CONFIRMED means stop or stay held until compliance records an outcome. The product state should be boring and explainable: pending compliance review, not a generic “something went wrong.”

This is the same split as KYC versus AML screening. KYC proved the name. Screening judged the name. Onboarding should wait on the screening outcome the same way it waits on a payment authorization: one stored id, one state, one owner.

Timeouts, retries, and the review queue

Do not blindly retry POST /api/v1/aml/screen after an upstream timeout. You may have created a screening you never stored. Reconcile first. If you already received a screening id, fetch it with GET /api/v1/aml/screenings/:id. If you never got an id, keep the customer pending and reconcile before you submit a second payload, so each customer carries one screening and one REVIEW case.

Use synchronous screening at signup, first payout, and new-counterparty checks. Naiza automatically re-screens existing customers on watchlist updates and supports full transaction monitoring alongside these checks. The AML integration guide has the request fields and event polling, and the AML screening API page covers list coverage and match results.

Give operations a queue they can finish. AUTO_CLEAR should not create a ticket. REVIEW should create one ticket, not one per retry. CONFIRMED should be loud inside compliance and quiet in marketing Slack.

If you are not ready to hold customers, run the same call in shadow: store the outcome, do not change activation. That is a rollout posture, not a different API. Flip to enforcing when the queue depth matches the number of reviewers you actually have, not the number you hope to hire.

The customer should feel one pending state or none. They should never feel a KYC wait, then a screening wait, then a “we are still checking lists” wait that nobody can point to an id for. If support cannot find the screening id from the account page, the integration is not done, even if the happy path is fast.