Troubleshooting

Common errors

The table below outlines common issues that may occur when using Socure Prefill in RiskOS™. These may stem from input formatting, incomplete data, provisioning gaps, or conflicting identity signals. Understanding these patterns helps fine-tune workflows, reduce null responses, and decide when fallback or escalation logic is needed.

Issue	Explanation	Suggested fix
No match / empty response	Inputs conflict, are incomplete, or do not resolve to a single SocureID.	Ensure consistent PII. Encourage users to provide accurate inputs. Prefill only returns data for a confident match.
Missing fields	Thin credit file, regional restrictions, or sparse data source coverage.	Anticipate incomplete attributes. Do not assume all fields will be populated.
Invalid input formatting	Incorrect formats (e.g., phone not in E.164).	Validate and normalize inputs before submission.
Not provisioned for Prefill	Workflow is missing entitlements for Prefill.	Confirm Prefill is enabled in your RiskOS™ environment.
API misconfiguration	Module not included in request (e.g., missing `"modules": ["prefill"]`).	Add correct module, confirm API key authentication, IP filtering, and workflow configuration.
Workflow rejection handling	Prefill data incorrectly exposed after a rejection.	Do not display Prefill results to end users if workflow returns a rejection.
Rate limiting / performance	High request volume or batch processing may hit rate limits.	Monitor API response times. Review rate limit documentation or consult support.
Third-party data variance	External data sources may return partial or inconsistent results.	Parse Prefill outputs carefully; handle nulls or partial matches gracefully in downstream workflows.

How to debug

To debug Prefill behavior in RiskOS™:

Use the eval_id to trace execution in the Developer Console or RiskOS logs.
Check the status_code in each data_enrichments[] block. 200 indicates success. Any other status should be flagged.
Confirm the "modules": ["prefill"] block is present in your request.
Review output carefully — an empty {} means inputs did not align with a single SocureID.
Check provisioning status if Prefill is missing from workflow execution.
Monitor latency: typical Prefill responses are 250–400ms in U.S. production.

Fallback strategies

If Prefill does not return data:

Normalize and retry. Remove accents, fix casing/whitespace, reformat phone/email.
Collect more signals. Supplying multiple PII fields (e.g., phone + email) improves resolution confidence.
Escalate gracefully. Route inconclusive cases to manual review or alternate enrichment modules.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue. Do this in sandbox or staging if possible.
Capture identifiers. Collect the following:
- eval_id
- Full request payload
- Workflow name
Open a support ticket. Contact Socure Support or your Technical Account Manager (TAM) with:
- Workflow configuration
- Input fields submitted
- Expected vs. actual Prefill output
- Logs or screenshots (if applicable)
Urgent escalation. For high-severity cases, escalate via Slack (if integrated) or your designated Socure escalation channel.

Known issues

International support is phone-only. Prefill cannot use email, SSN, or address signals outside the U.S.
Prefill is enrichment only. It does not perform compliance-grade verification (use Verify/Verify Plus for CIP/KYC).
Thin-file variance. Limited coverage for minors, new-to-credit, or sparse-data identities is expected.
Normalization quirks. Non-standard characters or unnormalized Unicode may cause null results. Pre-process inputs before submission.
Provisioning gaps. Missing entitlements will result in silent failures or skipped enrichments.

ℹ️
Note: Use the Developer Console to inspect raw Prefill requests/responses and confirm module execution in real time.