Watchlist Troubleshooting & FAQs

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.

Issue	Explanation	Suggested fix
Missing or invalid names	RiskOS™ 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 invalid	`entity_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 address	Unstructured 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 DOB	RiskOS™ 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 reappearing	Entities 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 created	Matches 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 confidence	Matches 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 expected	Known 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:

Reproduce the issue. Attempt in sandbox or staging first.
**Capture relevant identifiers.**Collect:
- eval_id
- Full request payload
- Any referenceId values
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)
**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.