## 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:

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](mailto:support@socure.com) 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.