AML Screening API

Sanctions, PEP, and watchlist screening endpoints.

Guides API Reference Code Examples Best Practices

AML API

The AML API lets you screen customers or entities against sanctions and AML watchlists, and submit AML event-monitoring payloads for transaction or counterparty workflows. It is available only to tenants with the AML Screening product enabled.

Auth

x-api-key is required. The tenant is always derived from the API key. Any tenantId in the request body is ignored.

If AML Screening is not enabled for your tenant, these endpoints return 403.

Endpoints

POST /api/v1/aml/events
GET /api/v1/aml/events/:externalEventId
POST /api/v1/aml/screen
GET /api/v1/aml/screenings/:id

Ingest an AML Event

Submits an AML event for tenant-scoped evaluation. The payload mirrors the fraud event shape for integration familiarity, but AML events do not enter the fraud events pipeline.

POST/api/v1/aml/events

Request

{
  "eventName": "payment.completed",
  "eventCategory": "TRANSACTION",
  "externalEventId": "aml_evt_ext_123",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com",
    "metadata": { "customer_type": "individual" }
  },
  "sourceReportedAt": 1672520400,
  "reference": "3cba8491-c0cd-44c6-8a72-78ca834db7f0",
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "payment_method": "card"
  },
  "custom_fields": {
    "counterparty_country": "US"
  }
}

Parameters

Field	Required	Description
eventName	Required by AML service	Tenant-defined AML event identifier, for example payment.completed
externalEventId	Required by AML service	Tenant-scoped unique id for polling and safe retries. Same id + same payload replays the stored result; same id + different payload returns 409. Not an Idempotency-Key header — reconcile with GET /api/v1/aml/events/:externalEventId after timeouts. Screening has no equivalent key; use GET /api/v1/aml/screenings/:id when you already have a screening id.
eventCategory	No	CUSTOMER, ACCOUNT, APPLICATION, CONTRACT, TRANSACTION, PAYMENT_INSTRUMENT or COUNTERPARTY
customer	No	Customer identifiers and optional metadata
device	No	Device identifiers, fingerprint, and optional metadata
ip	No	IP address from which the event originated
userAgent	No	User agent from the browser or application
country	No	ISO 3166-1 alpha-2 or alpha-3 country code
sessionId	No	Session identifier for related activity
sourceReportedAt	No	When the event occurred in the source system, as ISO string or Unix seconds
reference	No	External reference ID for tracking in your system
metadata	No	Custom metadata fields with bounded depth and size
custom_fields	No	Business-specific custom fields
payload	No	Legacy fraud-event payload forwarded as metadata.payload

Response

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

status can be CLEAR, ALERTED, HELD, APPROVED, or REJECTED. Current AML event results use CLEAR, ALERTED, and HELD; APPROVED and REJECTED are forward-compatible write-back statuses.

Poll an AML Event Result

Fetches the tenant-scoped AML event result by your externalEventId.

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

Response

{
  "externalEventId": "aml_evt_ext_123",
  "status": "ALERTED",
  "alerts": []
}

Screen an Entity

Runs a synchronous screening and returns the full result, including the decision and any watchlist matches.

POST/api/v1/aml/screen

Request

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

Parameters

Field	Required	Description
inputName	Yes	Full legal name of the entity to screen
externalId	Yes	Your system's identifier for the entity
entityType	No	INDIVIDUAL, ORGANIZATION, VESSEL or AIRCRAFT
inputDob	No	Date of birth (ISO 8601 date)
inputNationality	No	Nationality (ISO 3166-1 alpha-2)
inputAliases	No	Known aliases or alternate spellings
inputIdDocuments	No	Array of { type, value } identity documents
sensitivityProfile	No	CONSERVATIVE, BALANCED or LIBERAL (defaults to tenant config)

Response

{
  "id": "scr_abc123",
  "externalId": "cust_123456",
  "decision": "REVIEW",
  "processingMs": 142,
  "listsHit": ["OFAC_SDN"],
  "matches": [
    {
      "watchlistEntityId": "wl_987",
      "score": 92,
      "classification": "STRONG",
      "matchedName": "John Michael Smith",
      "entityName": "John M. Smith",
      "source": "OFAC_SDN",
      "sanctionReason": "Designated under E.O. 13224 for material support to a designated terrorist organization",
      "matchCity": "Damascus",
      "datesOfBirth": ["1965-03-12", "1965"],
      "scoreBreakdown": { "name": 0.95, "dob": 0.8 }
    }
  ],
  "caseId": "case_123",
  "alertId": "alert_123",
  "caseCreated": true,
  "reusedExistingCase": false
}

decision is one of AUTO_CLEAR, REVIEW or CONFIRMED.

Each match includes sanctionReason, matchCity, and datesOfBirth (full yyyy-mm-dd or year-only yyyy, for example ["1965-03-12", "1965"]). The optional caseId, alertId, caseCreated, and reusedExistingCase fields are present when AML auto-creates a case or links the alert to an existing open case.

Retrieve a Screening

Fetch a previously created screening by id. Results are tenant-scoped: a screening that belongs to another tenant returns 404.

GET/api/v1/aml/screenings/:id

Returns the same screening result shape as POST /api/v1/aml/screen.

Examples

curl -X POST https://api.naiza.ai/api/v1/aml/screen \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputName": "John Michael Smith",
    "externalId": "cust_123456",
    "entityType": "INDIVIDUAL"
  }'

curl -X POST https://api.naiza.ai/api/v1/aml/events \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "payment.completed",
    "eventCategory": "TRANSACTION",
    "externalEventId": "aml_evt_ext_123",
    "customer": { "externalId": "user_123456" },
    "metadata": { "amount": 99.99, "currency": "USD" }
  }'

Troubleshooting

401: missing or invalid API key
403: AML Screening is not enabled for your tenant
404: screening or AML event not found in your tenant scope
422: missing required field or invalid AML event payload
429: too many requests
502/504: the AML service was unavailable or timed out. For events, poll GET /api/v1/aml/events/:externalEventId. For screening, reconcile with GET /api/v1/aml/screenings/:id when you already have a screening id; do not blindly retry POST /api/v1/aml/screen.