SfSkills Domains Docs GitHub

Home / architect / aml-kyc-process-architecture

aml-kyc-process-architecture

Use when designing the architecture for AML/KYC compliance workflows on Salesforce — covering verification orchestration, third-party screening integration patterns, risk scoring design, and regulatory data flow.

Open the skill folder on GitHub

AML/KYC Process Architecture

Use this skill when designing the Salesforce-side architecture for Anti-Money Laundering (AML) and Know Your Customer (KYC) compliance workflows. It covers the orchestration layer that drives screening calls, the integration patterns for connecting to mandatory third-party sanctions and watchlist screening vendors, and the risk scoring design that produces regulatory customer risk ratings. This skill is architectural — it produces design artifacts, not implementation code.

Salesforce Financial Services Cloud (FSC) does not contain a native AML engine or sanctions screening service. The platform provides orchestration primitives (Flows, OmniStudio Integration Procedures, Apex callouts) and standard data model objects (notably PartyProfileRisk) that store and route results from mandatory third-party ISV screening calls. Every compliant AML/KYC architecture on Salesforce depends on an external screening vendor; this skill helps you design how Salesforce orchestrates those external calls and what it does with the results.

Before Starting

Core Concepts

FSC Has No Native AML Engine — Salesforce Is the Orchestrator

The most important architectural principle for AML/KYC on Salesforce is that FSC provides the workflow shell and data model, not the screening intelligence. Compliance decisions come from external vendors; Salesforce stores, routes, and surfaces them. The architecture must be designed around this separation of concerns:

A well-architected design treats the vendor API as a remote system with its own SLA and failure modes — not as a Salesforce extension.

PartyProfileRisk and the FSC Data Model

PartyProfileRisk is a standard FSC object that stores risk assessment records for individuals and accounts. Key fields:

PartyProfileRisk records are associated with an Individual record (the FSC person model), not directly with a Contact. This means the onboarding flow must ensure an Individual record exists before creating or updating a PartyProfileRisk.

Orchestration Layer Options

Three orchestration mechanisms are available, each with different tradeoffs for AML/KYC workflows:

  1. OmniStudio Integration Procedures — best for real-time, guided onboarding flows where a human is present and the screening result must be surfaced immediately in the UI. Integration Procedures are callable from OmniScript steps, can chain multiple API calls, and have built-in response mapping. Requires OmniStudio license.
  2. Apex callouts with Platform Events — best for fully automated, non-interactive screening (periodic review, batch re-screening). The Apex layer calls the vendor REST API, receives the response, and publishes a Platform Event. A separate subscriber flow or trigger processes the event and updates PartyProfileRisk. Decouples the screening call from the DML transaction.
  3. Screen Flow / Record-Triggered Flow — acceptable for simple low-volume cases where the vendor provides a reliable, fast synchronous API and onboarding volume is below a few hundred records per day. Synchronous callouts from Flows share the same 10-second callout timeout as Apex synchronous callouts. Do not use a record-triggered Flow with a synchronous callout for bulk-imported accounts.

Risk Scoring Design

Risk scoring in an AML context produces a customer risk rating (typically Low / Medium / High / Prohibited) based on a combination of factors: screening result, geography, product type, customer type (individual, corporate, PEP), and transaction behavior. Salesforce's Industries Scoring Framework uses CRM Analytics propensity models — it is designed for marketing and sales scoring, not for regulatory risk rating. Custom scoring logic is the standard pattern:

Common Patterns

Pattern A: Real-Time Screening via OmniStudio Integration Procedure

When to use: Guided onboarding flow with a human agent present; screening result must be visible in the OmniScript UI before the agent can advance; vendor exposes a REST API that responds within 3–5 seconds; onboarding volume is below ~500 records per day.

How it works:

  1. OmniScript collects customer identity data (name, date of birth, nationality, ID document).
  2. On a dedicated screening step, the OmniScript invokes an Integration Procedure.
  3. The Integration Procedure calls the vendor REST API via an HTTP Action element. The Named Credential stores the endpoint and credentials; no hardcoded secrets in the procedure.
  4. The Integration Procedure maps the vendor response to Salesforce fields using a DataRaptor Transform or inline DataWeave expression.
  5. The Integration Procedure performs a DML operation to create or update the PartyProfileRisk record with the screening result, risk category, and vendor case reference number.
  6. The OmniScript displays the result and, if a potential match is returned, routes to a compliance review queue via a Screen Flow or Case assignment rule.

Why not a record-triggered Flow: Record-triggered Flows that make synchronous callouts run inside the saving transaction. If the vendor API is slow or unavailable, the entire record save fails. This creates a poor user experience and risks data loss. OmniScript separates the screening step from record creation.

Pattern B: Asynchronous Batch Re-Screening via Apex + Platform Events

When to use: Periodic AML review of an existing customer portfolio; bulk import of new accounts; screening vendor operates a batch file interface rather than a real-time REST API; onboarding volume exceeds synchronous callout limits.

How it works:

  1. A scheduled Apex batch job (Database.Batchable) queries Individual or Account records due for re-screening based on PartyProfileRisk.RiskReviewDate.
  2. The batch job groups records and makes callouts to the vendor REST API in execute() scope (callouts from batch Apex execute methods are supported; the interface must implement Database.AllowsCallouts).
  3. For each vendor response, the batch job publishes a Platform Event (ScreeningResult__e) containing the vendor case reference, match status, and risk score.
  4. A separate Platform Event trigger or record-triggered Flow subscribes to ScreeningResult__e and updates the PartyProfileRisk record. Decoupling DML from the batch callout prevents governor limit collisions.
  5. Cases are opened automatically for potential matches via a Flow or Process Builder replacement; cases are assigned to a compliance review queue.

Why not a single synchronous Apex transaction: Each synchronous Apex transaction is limited to 100 callouts. For a portfolio of 50,000 customers requiring annual re-screening, the batch architecture with Platform Events is the only governor-limit-safe pattern.

Decision Guidance

SituationRecommended ApproachReason
Guided human-assisted onboarding, vendor has fast REST APIOmniStudio Integration Procedure + OmniScriptResponse surfaced inline; agent sees result before advancing
Automated onboarding, no human in loopApex callout (future or queueable) + Platform EventDecouples screening from record save; handles async response
Periodic portfolio re-screening at scaleScheduled Batch Apex + Platform EventsOnly pattern that handles callout limits for large data volumes
Vendor provides managed package, not raw REST APIFollow vendor's documented Salesforce integration patternVendor package may use its own objects; map results to PartyProfileRisk in a separate step
Risk scoring: rule-based, must be auditableCustom Apex scoring class writing to PartyProfileRiskDeterministic, explainable, no additional licensing required
Risk scoring: data-science model, CRM Analytics licensedCRM Analytics app + Apex writer classModel produces score; Apex writes result to RiskScore / RiskCategory
Vendor response may be delayed (async callback)Inbound REST endpoint on Salesforce (Remote Call-In pattern)Vendor POSTs result back; Salesforce updates PartyProfileRisk on receipt

Step-by-step instructions for an AI agent or practitioner working on AML/KYC process architecture:

  1. Confirm the platform baseline — verify FSC is enabled, identify the FSC license type, confirm whether OmniStudio is licensed, and establish which Salesforce edition (Enterprise or Unlimited) is in use. Record whether PartyProfileRisk is already in use or must be configured from scratch.
  2. Define the screening integration contract — identify the third-party screening vendor, obtain the vendor's API specification (REST endpoint, authentication method, request/response schema, SLA/timeout), and determine whether the vendor supports synchronous response or asynchronous callback (Remote Call-In pattern). Create a Named Credential for the endpoint.
  3. Select the orchestration pattern — using the Decision Guidance table above, choose OmniStudio Integration Procedure (guided/real-time), Apex callout + Platform Event (automated/async), or Batch Apex (periodic/bulk). Document the rationale in the architecture decision record.
  4. Design the risk scoring model — define the risk tier definitions (Low / Medium / High / Prohibited), list the inputs to the scoring decision (screening result, geography, customer type, product type), and choose the scoring implementation (rule-based Apex vs. CRM Analytics). Map outputs to PartyProfileRisk.RiskCategory, RiskScore, and RiskReason.
  5. Design the compliance review workflow — define what happens for each screening outcome: clear (auto-advance), potential match (route to compliance queue, open Case), confirmed match (block onboarding, escalate). Specify SLAs per outcome tier and design the Case assignment rules or Omni-Channel routing.
  6. Design the audit trail and data retention — identify which fields and events must be logged for regulatory audit (screening request timestamp, vendor response, risk decision, decision override with reason, reviewer identity). Determine whether Shield Field Audit Trail is required to meet retention obligations beyond the platform's 18-month field history.
  7. Validate the architecture against governor limits — calculate expected screening volume per day, per transaction, and per batch. Verify the chosen pattern stays within the 100 callout / 10-second timeout limits for synchronous paths and the batch size limits for asynchronous paths. Document the throttling and retry strategy for vendor API failures.

Review Checklist

Run through these before marking the architecture design complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Synchronous callouts inside record-triggered Flows are blocked for bulk operations — Record-triggered Flows that invoke a subflow or action making an HTTP callout will fail for records processed via bulk data load (Data Loader, Data Import Wizard, Apex DML on multiple records). The platform blocks synchronous callouts in bulk context. Any AML screening triggered by a record save must either be deferred to an async process or use a before-save Flow that only enqueues the work rather than executing the callout inline.
  2. PartyProfileRisk requires an Individual record, not a Contact — FSC's person model separates Individual (the person) from Contact (the CRM record). PartyProfileRisk is a child of Individual. If the onboarding workflow creates Contacts without creating corresponding Individual records (which is possible in standard Salesforce without FSC), there is no parent to attach a PartyProfileRisk to. Validate the Individual record exists — and has the expected IndividualId on the Contact — before attempting to create the risk record.
  3. Platform Events do not guarantee delivery order — In the asynchronous screening pattern (Apex publishes ScreeningResult__e, a Flow subscriber updates PartyProfileRisk), Platform Events are delivered at-least-once but not in guaranteed order. If two screening results for the same customer arrive close together (e.g., initial screen and an immediate re-screen), the older result could overwrite the newer one if the subscriber does not compare timestamps. Always include the screening timestamp in the event payload and guard the DML update with a timestamp comparison.
  4. The Industries Scoring Framework is not a regulatory risk engine — The FSC Scoring Framework (requires CRM Analytics Plus) generates propensity scores using CRM Analytics models. It is designed for marketing segmentation and sales prioritization. It does not produce audit-ready, explainable risk ratings suitable for AML regulatory purposes without significant custom governance layering. Presenting it to a compliance team as an AML risk engine will create a compliance gap.
  5. Named Credentials with Per-User authentication do not work in batch or scheduled Apex — Named Credentials configured with Per-User authentication require a user session to resolve the OAuth token. Batch jobs, scheduled jobs, and future methods run in a system context with no session — they will throw a callout exception. AML screening that runs in batch context must use Named Principal (org-level) authentication on the Named Credential, or use an external credential with a service account token.

Output Artifacts

ArtifactDescription
AML/KYC architecture documentComponent responsibilities, data flow diagram description, integration contract summary
Orchestration pattern decision recordSelected pattern, volume calculations, governor limit analysis, rationale
Risk scoring designTier definitions, scoring inputs, implementation choice, field mapping to PartyProfileRisk
Compliance review routing designOutcome-based routing rules, queue assignments, SLA definitions
Audit trail and retention specificationFields to log, retention period, Shield assessment

Package files