How to integrate AML screening via API
An AML screening API is an interface that takes a structured description of a party (a person or a company with the identifiers you hold) and returns a structured decision your systems can act on: clear, or a potential match with the evidence behind it. It lets an engineering team put sanctions, PEP and adverse-media screening directly inside an onboarding flow or a payment path, rather than running checks by hand. This guide sets out how a screening call works, what a request and response contain, how onboarding and payment integrations differ, how ongoing monitoring runs through an API, and how the automated calls and the case-management platform stay on one record.
An AML screening API is a programmatic interface that accepts a structured entity, resolves it against sanctions, PEP and adverse-media data, and returns a structured screening decision. Instead of a reviewer pasting a name into a tool, your application sends the party record over an authenticated connection and receives a result it can act on in line: proceed automatically when the party is clear, or route to a human reviewer when there is a potential match. That machine-to-machine pattern is what lets screening live inside a real-time onboarding or payment flow rather than sitting beside it as a manual step.
How does an AML screening API work?
At its core the API turns a screening question into a request and a decision into a response. Your system sends a party (a customer being onboarded, or a counterparty on a payment) with the identifiers you hold. The screening engine resolves that party against the underlying data, applies matching and entity resolution to separate genuine hits from noise, and returns a result your code can branch on. For onboarding and payment checks the call is synchronous, so the decision comes back within the request rather than in a later batch file. That is the property that lets you gate a flow: a clear result lets the customer or payment continue automatically, while a potential match pauses the flow and creates work for a reviewer. The engine does the resolution; your application decides what to do with the answer.
What does a screening request and response contain?
A request carries the party and its identifiers; a response carries the decision and the evidence. The more you send, the more precisely a match can be resolved, because sparse data forces matching to rely on the name alone, which is the least reliable signal available. An illustrative request and response looks like this:
POST /v1/screen
Authorization: Bearer <api_key>
Content-Type: application/json
{
"entity": {
"type": "individual",
"full_name": "Jordan Rivera",
"date_of_birth": "1978-04-12",
"country": "PT",
"identifiers": [{ "type": "passport", "value": "PT-4471902" }]
},
"datasets": ["sanctions", "pep", "adverse_media"]
}
// Response
{
"decision": "potential_match",
"matches": [{
"list": "OFAC SDN",
"score": 0.91,
"matched_name": "Jordan Rivera",
"match_reason": ["name", "date_of_birth"],
"case_id": "cs_8fd21a"
}]
}The decision field is what your code branches on. A clear result lets the flow continue; a potential_match returns each hit with the list it came from, why it matched, and a case reference the platform can pick up. Names, dates and structured fields are illustrative; the point is that the response is designed to be acted on by software, not just read by a person.
How do you integrate screening at onboarding vs in payments?
Both call the same engine, but they sit at different points. Onboarding screening runs once when a customer is created. You have a rich record to send and a little more tolerance for latency because a person is completing a form, and after the first check you typically enrol that customer for ongoing monitoring. Payment screening runs on every transaction that meets your criteria, often against sparse party data lifted from a payment message, and it has to return fast enough not to hold up settlement. The integration shape follows from that: onboarding is a check plus an enrolment, while payment screening is usually a stateless call that screens the parties on a single instruction. The two are covered in depth for payment screening and ongoing monitoring. Wire both to the same data layer so the customer and the payment are judged against one consistent set of lists.
How does ongoing monitoring work through an API?
Ongoing monitoring is enrolment, not a scheduled re-run you drive from your side. When you screen a customer at onboarding, you register that customer with the monitoring service through the same integration. From then on the engine re-screens the enrolled population against refreshed sanctions, PEP and adverse-media data, and raises an alert only when a customer's status changes, for example when a previously clear party becomes a new sanctions match. Your system learns about the change through a webhook (the engine calls you) or by polling a results endpoint, so you are not re-submitting every record yourself. This matters because a customer who cleared cleanly at onboarding can be listed later purely because a list changed, and a one-time check would never surface it. How often a given customer is re-screened should follow that customer's risk rating, a point set out in our ongoing monitoring frequency guide.
How is the API secured?
Screening requests carry customer identifiers, so the transport and the credentials matter as much as the screening logic. Calls run over TLS, authenticated with a scoped API key that your systems hold and rotate, never embedded in client-side code where it could be read. Keys are typically scoped so a compromised credential cannot do more than the integration needs, and separate keys are issued for sandbox and production so test traffic never mingles with live decisions. Identifiers should travel in the request body rather than in a URL query string, because query strings are logged in more places than a body is. On top of that, the results your application receives are the same evidence a regulator may later examine, so they are retained on a case record rather than left only in transient logs. Good API security here is ordinary good practice applied to sensitive data, not anything exotic.
How do the API and case-management platform stay in sync?
They stay in sync because both read and write the same case record rather than keeping separate copies. When the API returns a potential match, that result does not only come back to your application; it also creates or updates a case in the platform, carrying the entity, the matched list entry and the evidence, referenced by the case_id the response returned. A reviewer works the case, records a decision and the reason for it, and that outcome is written back to the record your systems can read. The effect is one audit trail spanning the automated call and the human review: what was screened, what matched, who decided, and why. This is how an engineering-led integration and a compliance team's investigation stay one story rather than two. The mechanics of that review sit in alert triage and case investigation, and the developer-facing detail lives on the developer documentation.
FAQ
How does an AML screening API work?
An AML screening API takes a structured description of a party, a person or a company with the identifiers you hold, and returns a structured decision that your systems can act on. Your application sends a request over HTTPS with the entity's name, and any supporting fields such as date of birth, jurisdiction or registration number. The screening engine resolves that entity against sanctions, PEP and adverse-media data, applies matching and entity resolution, and returns whether the party is clear or has potential matches, with the evidence behind each one. Because the response is machine readable, you can gate an onboarding flow or a payment on it automatically, routing only genuine hits to a human reviewer. The call is synchronous for onboarding and payment checks, so a decision comes back in line rather than through a batch file, which is what lets screening sit inside a real-time flow.
What is the difference between onboarding and payment screening integration?
Both call the same screening engine, but they sit at different points and carry different constraints. Onboarding screening runs once when a customer is created, so you have a richer record to send, the full name, date of birth, address and jurisdiction, and slightly more tolerance for latency because a person is completing a form. Payment screening runs on every transaction that meets your criteria, often against sparse party data drawn from a payment message, and it has to return a decision fast enough not to hold up settlement. The integration pattern differs accordingly: onboarding screening enrols the customer for ongoing monitoring after the first check, while payment screening is typically a stateless call that screens the parties on a single instruction. A firm usually needs both, wired to the same data layer so the customer and the payment are judged against one consistent set of lists.
Do you need a sandbox to integrate a screening API?
A sandbox is not strictly required, but integrating without one is a poor idea. A sandbox is a non-production environment that accepts the same request format and returns representative responses, including deliberate matches, so your engineers can build and test the integration without touching live customer data or real screening decisions. It lets you confirm that your code handles a clear result, a potential match and an error the same way it will in production, and that you parse the evidence correctly before anything goes live. Working against a sandbox also means you can rehearse the full flow, submit an entity, receive a decision, route a hit, without generating alerts that a compliance team then has to clear. Once the integration behaves correctly against representative data, you switch the base URL and credentials to production. Skipping this step tends to surface parsing and error-handling bugs at the worst possible moment, in live traffic.
How does ongoing monitoring work through an API?
Ongoing monitoring works by enrolling an entity once and then re-screening it automatically as the underlying lists change, rather than making you call the API on a schedule. When you screen a customer at onboarding, you register that customer with the monitoring service through the same integration. From then on, the engine re-screens the enrolled population against refreshed sanctions, PEP and adverse-media data, and raises an alert only when a customer's status changes, for example when a previously clear party becomes a new sanctions match. Your system receives that change through a webhook or by polling a results endpoint, so you learn about it without polling every record yourself. This matters because a customer who cleared cleanly at onboarding can be listed later purely because a list changed, and a one-time check would never surface it. The cadence of re-screening should follow each customer's risk rating rather than a single fixed interval.
How do the screening API and case-management platform stay in sync?
They stay in sync because both read and write the same case record rather than keeping separate copies. When the API returns a potential match, that result does not just come back to your application; it also creates or updates a case in the platform, carrying the entity, the matched list entry and the evidence. A reviewer works the case in the platform, records a decision and the reason for it, and that outcome is written back to the same record the API can read. The effect is a single audit trail that spans the automated call and the human review, so you can show a regulator what was screened, what matched, who decided, and why. Without this link, an engineering team's API logs and a compliance team's case notes drift into two disconnected stories. Keeping them on one record is what makes the decision defensible when it is examined months later.
Put screening inside your product.
Book a demo and we will walk your engineering team through the screening API, the sandbox, ongoing-monitoring enrolment, and how API hits and case management stay on one audit trail. Self-serve API or unified case management, on your terms.
Book a demo