Customer screening & monitoring

Introduction

This guide provides a comprehensive overview of how to configure AML customer screening and monitoring in SEON’s Fraud API and standalone AML API. Both APIs use the same config objects, as explained below.

API configuration

The API request follows a structured format, allowing customization of search parameters, including:

Monitoring frequency options

• Data source configuration
• Fuzzy search settings
• Result filtering
• Relevancy scoring
• Adverse media settings
• Default API request example

Default API request example

{
  "config": {
    "aml": {
      "version": "v1",
      "monitoring_required": true,
      "monitoring_schedule": "WEEKLY",
      "sources": {
        "sanction_enabled": true,
        "pep_enabled": true,
        "watchlist_enabled": true,
        "crimelist_enabled": true, 
        "adversemedia_enabled": false,
        "local_aml_sources":{
               "brazil_spa":true,
               "bolsa_familia":true,
               "cpf_based_pep":true,
               "cpf_based_ppe": true,
               "cpf_based_ppn": true,
               "seguro_defeso": true,
               "garantia_safra": true,
               "auxilio_emergencial": true,
               "brazil_bpc": true
            }
      },
      "fuzzy_enabled": true,
      "fuzzy_config": {
        "phonetic_search_enabled": false,
        "edit_distance_enabled": true,
        "scoring": {
          "result_limit": 10,
          "score_threshold": 0.585,
          "edit_distance_1_threshold": 3,
          "edit_distance_2_threshold": 5,
          "phonetic_term_threshold": 5,          
          "phonetic_character_threshold": 12,
          "min_nr_token_match": 67,
          "enable_lastname_detection": false,
          "filter_missing_dob": false,
          "filter_mismatching_dob": true,
          "glued_words_splitting": "off",
          "adverse_media_scores":{
                  "force_dob_filter":false,
			  "force_country_filter": false,
                  "fuzziness":0.6,
                  "exact_match":false
          }   
        }
      }
    },
    "aml_api": true,
    "response_fields": "aml_details",
    "user_fullname": "John Doe",
    "user_country": ""
  }
}

Explanation of key parameters

How to enable customer screening & monitoring

There are three essential steps required in all API calls:

• The aml_api parameter must be set to true.
• The request must include the AML configuration, which must contain version information and monitoring details: "config":{"aml":{"version": "v1","monitoring_required": false}}
• To receive the correct fields in the response, AML details must be enabled using the parameter: "response_fields":"aml_details"

Monitoring frequency

The API allows users to configure how often searches are monitored for updates.

• monitoring_required: Can be set to true or false.
• monitoring_schedule: Configurable with the following options:
  • ON_CHANGE – Triggers monitoring whenever a data source is updated.
  • DAILY, WEEKLY, MONTHLY, QUARTERLY, TWICE_A_YEAR, EVERY_YEAR – Allows users to customize monitoring frequency.

Monitoring frequency customization

• Customers can define specific monitoring schedules for different sources (e.g., sanctions checked ON_CHANGE, PEP checked YEARLY).
• Source-specific schedules can be set via the Admin/UI under Settings ? System ? AML ? Monitoring. In this case, monitoring_schedule should be "monitoring_schedule": null in the API request, as the API hierarchy always takes precedence and will override Admin/UI settings.
• Person-specific schedules can be set by adding a specific monitoring_schedule to the API request. This will always override account-wide settings.
• Scheduling example:
  • If the monitoring schedule changes (e.g., from DAILY to MONTHLY), the next run is recalculated based on the updated_at field.
  • Example: If PEP monitoring changes from DAILY to MONTHLY on February 14, the next check will be on March 14.

Source configuration

For Person searches, the following parameters can be used to enable/disable sources:

• sanction_enabled
• pep_enabled
• watchlist_enabled
• crimelist_enabled
• adversemedia_enabled (Adverse Media source includes additional costs)
• Local data sources (source includes additional costs)
  • brazil_spa: (Brazilian sports related persons)
  • bolsa_familia: (Persons who receive Bolsa Família aid in Brazil.)
  • cpf_based_pep (Brazil local PEP database with CPF identifier)
  • cpf_based_ppe
  • cpf_based_ppn
  • seguro_defeso
  • garantia_safra
  • auxilio_emergencial
  • brazil_bpc

For Entity searches, only sanction_enabled and watchlist_enabled are available.
 

Fuzzy Search Configuration

• fuzzy_enabled: Enables fuzzy search when set to true.
• phonetic_search_enabled: Enables phonetic search (disabled by default). Only works if a name tokens at least 5 character long.
• phonetic_term_threshold: (Default: 5) If a word in the input is shorter than this value, phonetic search won’t be applied to it. Example: With a threshold of 5, “John” is skipped, but “Albert” is included.
• phonetic_character_threshold: (Default: 12) If a word has more characters than this value, phonetic search is enabled – only if phonetic search is turned on.
• edit_distance_enabled: Allows for typo tolerance in searches. (enabled by default)
• edit_distance_1_threshold: Defines how many character changes are allowed for short terms.
• edit_distance_2_threshold: Defines how many character changes are allowed for longer terms.
• min_nr_token_match: Defines the percentage of name tokens that must match for a valid comparison. Default: 67 (at least 67% of tokens must match). Range: 0 - 100 (100 requires a full match). Example: With 67, "Alexander Gahon Gesmundo" matches "Alexander Gesmundo", but with 100, it does not. Adjust for stricter or more flexible name matching.
• enable_lastname_detection: Default: false, Function: When enabled, the search name and result name are split into first name(s) and last name(s). The filter only applies if a contradiction is detected.
  • How It Works:
    • Match: "John Smith" and "John Adam Smith" ? Not filtered out (since "Adam" could be a middle name).
    • No Match: "Adam Smith" and "John Adam Smith" ? Filtered out (since "Adam" is a first name in one case but a middle name in the other, creating a contradiction).
• glued_words_splitting: Handles names that may be incorrectly merged. Options:
  • off: Never used (default).
  • on: Always active.
  • fallback: Used only when no exact match is found.

Result filtering

• filter_mismatching_dob: If set to true, it filters out all results where there is a discrepancy between the searched date of birth (DOB) and the matched records based on name similarity but with a different DOB.
• filter_missing_dob: When enabled, if you provide a date of birth (DOB) in your request but the source data does not include a DOB, the result will be excluded from the search results.

Scoring Parameters

• result_limit: Limits the number of results returned.
• score_threshold: Sets the minimum relevancy score for results to be included. (Recommended:  0.585)

Adverse Media Matching (If Enabled)

If adverse media searches are enabled, additional fuzzy search settings apply:

• Fuzziness Level: Recommended 0.6 (Higher values return more loosely matching results)
• exact_match: If it is set to false, flexible matching allowed
• force_dob_filter:  If it is set to true only names without full DOB match is included

Advanced fuzzy parameters

Besides the recommended fuzzy configuration, there is an alternative scoring system that excludes date of birth (DOB) from the matching logic. This allows our scoring system and fuzzy matching logic to rely solely on name matching if required.

To enable this, the scoring object must include the following configuration:

"advanced_params": {
   "name_similarity_enforced": true
}

Important:

• The recommended scoring threshold in this case is 0.8, not 0.585.
• A lower threshold may lead to too many false positives.

Example API request with advanced fuzzy parameters:

{
  "config": {
    "aml": {
      "version": "v1",
      "monitoring_required": true,
      "monitoring_schedule": null,
      "sources": {
        "sanction_enabled": true,
        "pep_enabled": true,
        "watchlist_enabled": true,
        "crimelist_enabled": true, 
        "adversemedia_enabled": false
      },
      "fuzzy_enabled": true,
      "fuzzy_config": {
        "phonetic_search_enabled": false,
        "edit_distance_enabled": true,
        "scoring": {
          "result_limit": 10,
          "score_threshold": 0.8,
          "edit_distance_1_threshold": 3,
          "edit_distance_2_threshold": 5,
          "min_nr_token_match": 67,
          "enable_lastname_detection": false,
          "filter_missing_dob": false,
          "filter_mismatching_dob": true,
          "adverse_media_scores":{
                  "force_dob_filter":false,
                  "fuzziness":0.6,
                  "exact_match":false
          },
          "glued_words_splitting": "off",
          "advanced_params": {
            "name_similarity_enforced": true
          }
        }
      }
    },
    "aml_api": true,
    "response_fields": "aml_details",
    "user_fullname": "Geleri Omer",
    "user_country": ""
  }
}

Understanding API responses

Response structure

{
  "success": true,
  "data": {
    "has_sanction_match": true,
    "sanctionlist_entries": [
      {
        "found": "fuzzy",
        "id": 215909,
        "name": "John Doe",
        "scores": { "relevancy_score": 0.7497 },
        "source": {
          "source_name": "latvia-fid",
          "source_full_name": "Financial Intelligence Service of Latvia",
          "source_version": "2024-03-30"
        },
        "birth_date": "1958-08-17",
        "nationality": "Indonesia",
        "program": "TAQA"
      }
    ]
  }
}

Response structure

The API response consists of three main components:

• Success & error status
• Match indicators
• Detailed match information

Success & error status

• "success": true ? The request was processed successfully.
• "error": {} ? No errors occurred during the request.

Match indicators

These Boolean flags indicate whether the searched individual or entity appears on specific lists:

• "has_watchlist_match": "false" > No matches found in global watchlists.
• "has_sanction_match": "true" > The individual/entity appears on one or more international sanction lists.
• “has_crimelist_match”: “false” > No matches found in criminal databases.
• "has_pep_match": "false" > The individual/entity is not classified as a Politically Exposed Person (PEP).
• “has_adversemedia_match”: “true” > The individual/entity has been linked to negative media coverage.

Local AML Match Indicators

These flags show whether the individual/entity matches local Anti-Money Laundering (AML) criteria:

For example:

• "has_brazil_spa_match": "true" > The individual/entity appears on Brazil’s SPA list.
• “has_bolsa_familia_match: "true” > The individual/entity is listed on Brazil’s Bolsa Família program.
• "has_cpf_based_pep_match": "true" > The individual/entity is classified as a PEP based on CPF records.

Detailed match information

Sanction list matches

• The "sanctionlist_sources" array provides details on sanctioning authorities, including:
  • Source name (e.g., "ofac-sdn", "un", "eu")
  • Full source name (e.g., "Office of Foreign Assets Control (OFAC)")
  • Last update version (e.g., "2024-04-03")
• The "sanctionlist_entries" section contains records of matched individuals, including:
  • Name (e.g., "John Doe")
  • Match type ("fuzzy" > Indicates a possible name variation)
  • Relevancy score (0.7497 ? Higher score indicates stronger match)
  • Source details (e.g., "Financial Intelligence Service of Latvia")
  • Additional identifiers (e.g., Date of Birth, Nationality, Sanctions Program, Aliases)

Adverse media matches

• The "adversemedia_entries" array contains reports linking the individual to media publications related to financial crime, fraud, or terrorism.
• Includes:
  • Media snippet (Excerpt from the report)
  • Publication date
  • News source & URL

Local AML data (Brazil-specific)

• "local_aml_entries" contains data on Brazilian betting restrictions, showing whether the individual is restricted from gambling due to potential integrity risks.

How to interpret the results

• If "has_sanction_match": "true", the entity is listed on global sanctions databases, and further due diligence is required.
• "has_adversemedia_match": "true" suggests potential reputational risks and should be investigated.
• A "relevancy_score" close to 1.0 indicates a high-confidence match.
• Review "sanctionlist_entries" and "adversemedia_entries" for supporting details, such as aliases, nationalities, and sources.

Next steps for integration

• Automate compliance checks: Use this API for real-time screening against global sanctions, watchlists, crime lists and adverse media.
• Apply risk-based decisions: Set thresholds for automatic flagging based on relevancy scores and list types.
• Perform manual review: High-confidence matches should be reviewed by a compliance officer before taking action.