Best Practices for Your API Implementation

Screening Scope: Use Categories or List Sources

When configuring your screening requests, always specify either list_source_categories or list_sources — never individual list names.

Why This Matters

Categories and list sources remain stable over time. Individual list names within sources frequently change:

• New programs are added (e.g., new sanctions regimes)
• List names are updated to reflect policy changes
• Deprecated lists are removed

Example:

{
  "list_source_categories": ["Sanctions"]  // ✓ Recommended
}

{
  "list_sources": [
    {
      "name": "OFAC SDN",
      "category": { "name": "Sanctions" }
    }
  ]  // ✓ Also acceptable
}

{
  "lists": [
    { "name": "DPRK" },
    { "name": "Iran" }
  ]  // ✗ Not recommended - lists change frequently
}

Applying to Monitoring

This same principle applies when setting up monitors. Configure your monitor parameters with list_source_categories or list_sources to ensure your monitoring remains effective as watchlist coverage evolves.

Flatten Catchall Parameter

The flatten_catchall parameter (available in /screen_entities batch endpoint) controls how additional list entry data is formatted in responses.

• Default: false (catchall data is structured)
• Set to true: Flattens catchall information into a simpler format

When to use: Enable flattening (true) if your system needs catchall data in a flat structure for easier parsing or display.

{
  "screen_entity_queries": [...],
  "flatten_catchall": true
}