AML Integration

Use AML integration when you need sanctions and AML screening for customers, entities, counterparties, or transaction events.

1. Screen a customer or entity during onboarding or review.
2. Send AML events for activity that should be evaluated.
3. Hold or route risky events while AML evaluates them.
4. Poll by external event id when your system needs write-back.

Screen Customers and Entities

Call POST /api/v1/aml/screen when you need a synchronous screening result for onboarding, re-screening, or manual review.

POST /api/v1/aml/screen

{
  "inputName": "John Michael Smith",
  "externalId": "cust_123456",
  "entityType": "INDIVIDUAL",
  "inputDob": "1985-04-12",
  "inputNationality": "GB",
  "inputAliases": ["Johnny Smith"],
  "sensitivityProfile": "BALANCED"
}

• AUTO_CLEAR - no material match was found.
• REVIEW - a possible match needs investigation.
• CONFIRMED - the screening matched a confirmed watchlist entity.

Send AML Events

Use POST /api/v1/aml/events for activity that should be checked by AML event rules, such as transaction or counterparty updates.

POST /api/v1/aml/events

{
  "eventName": "payment.completed",
  "eventCategory": "TRANSACTION",
  "externalEventId": "aml_evt_ext_123",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com"
  },
  "sourceReportedAt": 1672520400,
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "payment_method": "card"
  },
  "custom_fields": {
    "counterparty_country": "US"
  }
}

externalEventId should be stable and unique per tenant. Retries with the same id and payload replay the stored result; a different payload with the same id returns 409. After timeouts, poll GET /api/v1/aml/events/:externalEventId — this is not an Idempotency-Key header. Screening has no equivalent key; reconcile with GET /api/v1/aml/screenings/:id when you already have a screening id.

Rules, Holds, and Outcomes

AML event status can be CLEAR, ALERTED, HELD, APPROVED, or REJECTED.

Use HELD when the product should pause fulfillment while compliance reviews the event.

Poll Write-Back Results

Poll by externalEventId when your system needs the current AML result.

GET /api/v1/aml/events/:externalEventId

{
  "externalEventId": "aml_evt_ext_123",
  "status": "ALERTED",
  "alerts": [
    {
      "id": "aml_alert_123",
      "severity": "HIGH",
      "summary": "Counterparty matched a sanctions rule"
    }
  ]
}

Recommended Product Behavior

• Run customer screening before high-risk product access.
• Send AML events for money movement and counterparty changes.
• Persist screening ids, external event ids, and case references.
• Treat REVIEW, CONFIRMED, ALERTED, and HELD as operational handoff points.

Related References