Troubleshooting

Common errors

The table below outlines common errors that may occur when calling the Phone Risk enrichment. These issues often stem from input formatting, incomplete or invalid data, velocity anomalies, or evolving model behaviors. Understanding these patterns can help you fine-tune workflows, reduce false positives, and determine when escalation or fallback logic is appropriate.

Issue	Explanation	Suggested fix
Low correlation or unexpected risk scores	Name and phone number do not historically correlate; international numbers have lower coverage; business/role-based numbers often show weak correlation.	Review troubleshooting page. If capturing address as a supporting signal, submit apartment/unit in a dedicated field, ensure USPS formatting, and validate with an address verification service before submission.
Missing or invalid output	Required fields (e.g., phone number) not provided; request payload not structured correctly; unsupported characters or encoding issues.	Confirm required fields are present (at minimum `data.individual.phone_number` in E.164). Check field names against docs. Ensure UTF-8 encoding; remove unsupported symbols and whitespace artifacts.
Frequent errors or API failures	Rate limits exceeded; authentication issues; incorrect endpoint usage.	Monitor request volume vs. rate limits. Verify API keys/tokens are valid/active. Confirm endpoint URLs and check for recent API updates in DevHub/Docs.
Unexpected model behavior after release updates	Model version changed with new logic or data sources; thresholds/decision rules not updated to align to latest version.	Check current model version returned in `phoneRisk.scores[].version`. Review release notes for scoring changes. Re-evaluate thresholds and rules; contact Socure for tuning recommendations.

How to troubleshoot results

If Phone Risk results appear unexpected or incomplete, start with the following checks:

Confirm inputs were provided correctly: Verify that the phone number was included in the request and formatted consistently, and that required supporting fields (such as country information) were provided where applicable.
Verify enrichment execution: Ensure that the Phone Risk enrichment was included in the workflow and executed as expected for the request being evaluated.
Review returned outputs: Check that risk scores, correlation values, or explanatory indicators were returned, and that they align with the inputs provided.
Evaluate correlation context: Name–phone correlation results depend on the availability and consistency of name attributes. If name information is missing or inconsistent, correlation outputs may be limited.
Assess results in context: Phone Risk signals are intended to be interpreted alongside other workflow signals and business rules, rather than in isolation.

Fallback strategies

If Phone Risk does not yield a clear result:

Reprompt for correction. Ask users to re-enter the phone number in E.164 format (+ country code + national number).
Chain enrichments. Use email risk, document verification, device risk, or address signals for additional confidence.
Step up verification. Trigger OTP or documentary verification when high-risk reason codes are present.
Escalate to review. Use tags or review_queues to route suspicious or inconclusive cases to analysts.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue. Try in sandbox/staging with the same payload.
Capture identifiers. Collect:
- eval_id
- Full request payload
- referenceId from the Phone Risk enrichment
Open a support ticket. Contact Socure Support or your Technical Account Manager (TAM) with:
- Workflow name
- Input fields submitted
- Expected vs. actual decision
- Logs or screenshots (if applicable)
Urgent escalation. For high-severity cases, escalate via:
- Slack (if integrated)
- Your designated Socure escalation channel

Known issues

International coverage variability. Some markets have thinner data; correlation may be lower for certain country/number types.
Business/role-based numbers. Corporate PBX or shared service lines typically have weak name–phone correlation.
Number portability/recycling. Recently ported or recycled numbers can produce inconsistent signals until history stabilizes.
Formatting & normalization. Non-E.164 or unnormalized Unicode can cause validation failures; normalize before submission.
Durable vs. risky signals. Consider positive indicators (e.g., long-tenured carrier history) alongside neutral risk scores when tuning decisions.

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