User Guides
Home

Troubleshooting and FAQs

Learn how to test, debug, and optimize your integration using RiskOS™ Watchlist.

Common issues

The table below outlines common issues that may occur during watchlist screening in RiskOS™. These problems typically arise from malformed inputs, incomplete data, or configuration choices. Understanding these patterns can help reduce false positives, minimize errors, and improve alert management.

IssueExplanationSuggested fix
Missing or invalid namesRiskOS™ may error, skip, or return irrelevant matches if name fields contain placeholders (TEST, N/A, XXXX, 12345).Validate name fields. Avoid placeholders and numeric-only values. If missing, provide at least two strong identifiers (DOB + ID + address).
Entity type omitted or invalidentity_type must be INDIVIDUAL, ORGANIZATION, VESSEL, AIRCRAFT, or OTHER. Omitted → defaults to OTHER. Invalid → request rejected.Supply the correct type when known. Use DOB → INDIVIDUAL; legal suffixes → ORGANIZATION. If unsure, omit and allow default behavior.
Incomplete or malformed addressUnstructured or partial addresses lower match confidence.Validate against ISO 3166-1 country codes and proper postal formats. Strengthen other identifiers if address is unreliable.
Malformed or partial DOBRiskOS™ supports YYYY, YYYY-MM, YYYY-MM-DD. Invalid (e.g., 31-31-2000) or partial values may be skipped.Normalize DOBs pre-submission. Align tolerance (Exact, ±1 year, digit transposition) with data quality. Audit with dobExact, dobFuzzy, etc.
Accept list matches reappearingEntities previously suppressed may trigger new alerts if profile data changes (DOB, aliases, names).Suppression is context-sensitive. Review case_reason and match_source fields to understand what changed.
Alerts logged but no cases createdMatches may appear in logs without creating cases if accept lists, deduplication windows, or suppression policies apply.Check your policy config. Look for alert_status: suppressed. Suppressed alerts are audit-visible but won’t trigger workflows.
Unexpected match confidenceMatches may appear too strong or too weak due to missing disqualifying data or overweighting of partial inputs.Strengthen input data (full name, DOB, ID). Check match_fields and match_score. Use debug: true for deeper testing visibility.
No match when expectedKnown sanctioned entities may not return results due to input errors, type mismatches, sandbox mode, or accept list suppression.Check input formatting. Confirm you are testing in production. Review suppressions and retry with corrected inputs.

How to debug

To debug Watchlist behavior in RiskOS™:

  • Use the eval_id to trace execution in the Developer Console or RiskOS™ logs.
  • Check the status_code in each screening block. A 200 indicates success. Any other status should be flagged.
  • Validate which modules were triggered. If a watchlist query was expected but not called, confirm required inputs (e.g., full name, DOB, entity type) were present.
  • Review match_fields and match_score for detail on why results scored as they did.
  • Examine case_reason and match_source when alerts reappear.
  • Confirm that suppression and deduplication policies are configured as intended.

Fallback strategies

If Watchlist does not yield a confident match:

  • Enable partial match tolerance. Accept lower thresholds in low-risk flows (e.g., name + DOB match but address fails).
  • Strengthen alternate identifiers. Add DOB, ID, address, or phone when names are weak.
  • Retry with normalized inputs. Remove accents, casing issues, and redundant whitespace.
  • Escalate to review. Use tags or review_queues to route inconclusive results to human analysts.

Escalation path

For production-impacting issues or debugging edge cases:

  1. Reproduce the issue. Attempt in sandbox or staging first.
  2. Capture relevant identifiers. Collect:
    • eval_id
    • Full request payload
    • Any referenceId values
  3. Open a support ticket. Contact Socure Support or your Solutions Consultant team with:
    • Workflow name
    • Input fields submitted
    • Expected vs. actual result
    • Logs or screenshots (if available)
  4. Urgent escalation. For critical cases, escalate via:
    • Slack (if integrated)
    • Your designated Socure escalation channel

Known issues

  • Suppression is context-sensitive. Entities may reappear if profile attributes change.
  • Thin input coverage. Weak identifiers (e.g., name-only submissions) lead to higher false positives.
  • Normalization requirements. Non-UTF8 or unnormalized Unicode characters may trigger errors. Normalize inputs before submission.
  • Policy suppression visibility. Alerts suppressed by policy are logged but will not create cases.
📘

Note:

Use the Developer Console to view raw request/response logs in real time for debugging or validation.


FAQs

General product behavior

Why should I have different screening and monitoring policies?

In practice, many organizations tune screening and monitoring differently to balance risk management with operational efficiency.

Different settings for different lists

  • Sanctions (e.g., OFAC): Screening often uses looser parameters due to high regulatory scrutiny and the serious consequences of missing a true match.
  • PEP and Adverse Media: Screening can use tighter parameters because these lists are larger and context-dependent. Stricter settings help manage volume and align with risk-based handling.

Different list priorities for screening vs. monitoring

  • Screening: At onboarding, companies often sweep broadly across OFAC, PEP, and Adverse Media.
  • Monitoring: Ongoing monitoring typically focuses on OFAC and PEP, since they update frequently and carry higher regulatory consequences.
  • Adverse Media: Often rescreened periodically or targeted to high-risk segments.

👉 The goal: keep screening broad enough to avoid missing risk at entry, while keeping monitoring focused to reduce noise and alert fatigue.

What is the difference between screening and monitoring in Watchlist?
  • Screening: A point-in-time check (onboarding, rescreening) to block risky users before access.
  • Monitoring: Ongoing checks for existing customers as lists update (new additions, updates, or removals).

Input and matching

How does fuzziness relate to the Name Match Score?

Other systems expose fuzziness tolerance as a tuning parameter. RiskOS™ uses a Name Match Score that incorporates algorithms and ML techniques.

  • Fuzziness is inversely proportional to the Name Match Score: higher fuzziness → lower score.
  • Example thresholds: strict tolerance = only scores above 80; loose tolerance = allow scores as low as 50.

Match Type and Thresholds

Match TypeLower ThresholdFuzziness ToleranceWhen to Use
Very Weak Match20–2590–100%Broad sweeps, investigative audits
Weak Match30–4560–80%Wide-net or sanctions screening
Fuzzy Match50–6040–50%Standard for sanctions; balance recall and precision
Strong Match75–8220–30%Ongoing monitoring, PEP screening
Very Strong Match9010%Very strict, small variations only
Exact Match1000%Character-for-character match
What input data is required for an evaluation?
  • Minimum: a plausible full name (given/family or entity name).
  • Additional inputs (DOB, national ID, address) reduce false positives.
  • Invalid placeholders (TEST, N/A, 12345) may cause errors.
  • API rejects mismatched entity types or invalid field combinations.
What entity types can be screened, and how do I specify them?
  • Supported types: individuals, organizations, vessels, aircraft, others.
  • Can be set in the dashboard or in each API request.
  • If omitted → defaults to OTHER, broadening results and possibly increasing false positives.
Are certain fields (like surname) always required?
  • Surname is required for Watchlist Plus and Premier modules for individuals.
  • Missing surname may cause invalid request errors.
  • For organizations: use entity_name and entity_type.

Errors and debugging

Why did I get reason code R640 for China when China is not an OFAC sanctioned country?

OFAC administers many targeted sanctions, not only comprehensive ones.

R640 may be triggered for sectors like:

  • Defense and surveillance tech
  • Human rights violations in Xinjiang
  • Illicit oil trade with Iran
  • Individuals/entities linked to fentanyl trafficking
Why do I see an 'Inactive entityId' error when attempting watchlist suppression?

This means the entity is no longer active in the source list.

  • The entity may have been removed or no longer meets criteria.
  • Verify whether the entity exists in the list. If not, suppression is unnecessary.

👉 Best practice: check entity status before suppression.

Why am I getting a 'Module processing error' or persistent timeouts?
  • Common cause: a very common name producing an oversized candidate pool.
  • Usually resolved by processing optimizations.
  • If persistent, contact support.
Why does Case Management show 'Error loading case management'?

Possible causes:

  • Navigating to invalid page numbers
  • Disabled or misconfigured roles
  • UI bugs (e.g., NaN pagination)
  • Case review workflow not configured

Try toggling between 1-step and 2-step workflows.

I changed policy settings but still see old behavior. Why?
  • Policy changes only apply to new evaluations created after publishing.
  • Cases created before the change reflect old rules.
  • Verify timestamps vs. policy change logs.

Product scope and configuration

Which lists are included at each Watchlist tier?
  • Standard: ~50–60 core sanctions/enforcement lists (OFAC, UN, EU, UK, OIG, HIDTA).
  • Plus: Adds 1,400+ global lists and 10,000+ PEP records.
  • Premier: Adds 10M+ adverse media articles, 40+ extra lists, SOE data, and wider language coverage.
Why do I see extra AKAs or differences across sources?
  • Socure aggregates aliases (AKAs) via entity resolution.
  • All AKAs linked to a resolved entity are surfaced, regardless of list source.
  • Some compliance teams prefer per-source separation for transparency.
Why do I get hits on foreign watchlists, or how do I enable/disable lists?
  • Policies and tiers determine list usage.
  • In dashboard, exclude regions or lists per policy.
  • Use sub-accounts to separate domestic vs. international flows.
Why does behavior differ between Sandbox and Production?
  • Sandbox responses are mocked and not all lists/features are available.
  • Production includes live list updates and monitoring APIs.
What are best practices for portfolio import and suppressing duplicate alerts?
  • Use batch jobs (CSV) to load customers for monitoring.
  • Mark previously reviewed entities as accepted to suppress repeats.
  • Include your reference ID and flags (acceptList, autoMonitoring).
How should I approach thresholds for sanctions vs. PEP/adverse media?
  • Sanctions: Regulators expect near-zero false negatives → use broader thresholds, tolerate more reviews.
  • PEP/adverse media: Tune thresholds higher or limit monitoring to high-risk groups to reduce fatigue.

Updated 10 days ago