Skip to main content

AML v2 → v3 Migration Guide

Who this applies to: Partners currently on AML v2 who are upgrading to AML v3, or partners who have already been moved to v3 and haven't updated their webhook handler yet.

What's changing in the webhook​

Three things are different in the v3 webhook payload:

  • Status field is renamed — Read status instead of alert_status
  • Status values are renamed — ACCEPTED is now ACTIVE, DECLINED is now STOPPED
  • Nationality format changes — 3-letter codes (GBR) become 2-letter ISO codes (GB)
  • New optional field — aml_check contains enriched data (PEP, sanctions, adverse media). You don't need to use it, but it's there if you want it.

Do I need to update right now?​

It depends on which field your integration reads:

  • Reading alert_status → You're safe for now. The old values (ACCEPTED/DECLINED) are still sent for backwards compatibility. No immediate action needed, but plan to migrate — this field is deprecated and will be removed in a future release.
  • Reading status → Update immediately. The values are ACTIVE and STOPPED — if your code expects ACCEPTED/DECLINED from this field, it will fail silently or break.
  • Using nationality codes → Update your handling to accept both 2-letter and 3-letter formats, or switch fully to 2-letter.

What to update​

WhatBefore (v2)After (v3)
Field to readalert_statusstatus
"All clear" valueACCEPTEDACTIVE
"Flagged" valueDECLINEDSTOPPED
Nationality formatGBRGB
  1. Confirm with the integrations team that your account has been moved to v3
  2. Update your webhook handler to read status instead of alert_status
  3. Replace ACCEPTED/DECLINED checks with ACTIVE/STOPPED
  4. Update any nationality handling to use 2-letter codes
  5. Test against a sandbox webhook event before going live