Troubleshooting and FAQs

Common errors

The table below covers issues that can occur during Verify or Verify Plus evaluations. These are typically caused by input formatting, missing data, provisioning differences, or ambiguous identity resolution. Use these patterns to improve data collection, tune routing, and decide when to step up verification.

Issue	Why it happens	Suggested fix
Drop in auto-acceptance rates	Changes in applicant traffic, data quality, or workflow configuration can shift outcomes.	Compare recent traffic to baseline (inputs, region, device, channel). Confirm workflow changes, required fields, and routing rules. Review evaluation tags and reason codes in the RiskOS Dashboard.
Deceased signal conflicts	Source data can be delayed, inconsistent, or mismatched due to name/DOB formatting.	Verify the applicant’s legal name and date of birth formatting. Route to review or step-up verification when signals conflict.
Multiple users share a national ID	Data entry issues, shared/incorrect identifiers, or commingled records can cause ambiguity.	Validate the identifier format. Collect additional linking fields (phone, email, address). Route to review when resolution remains ambiguous.
Same user appears with different dates of birth	Corrections, aliases, or ambiguous resolution can occur across sources.	Reprompt for DOB and legal name. Consider step-up verification or review for conflicts.
Invalid national ID	Format doesn’t match expected syntax for the region.	Validate format client-side before submission and normalize input.
Name mismatch but identifier matches	Typos, aliases, or first/last reversal.	Reprompt to confirm legal name. Apply configured match tolerance settings if appropriate.
Partial match on household attributes	A relative or household member is the closest match.	Collect additional linking fields and/or step up to documentary verification.
Invalid DOB	Malformed or ineligible date.	Enforce ISO date format and apply age eligibility checks before calling the API.
Address not found / undeliverable	Formatting or deliverability issues.	Normalize address input and reprompt for a physical address when required.
Special characters / diacritics cause mismatches	Normalization or transliteration differences.	Preserve Unicode where supported, but normalize whitespace/punctuation consistently. Avoid stripping characters unless required by your system.
Ambiguous identity resolution	Common names or limited inputs reduce confidence.	Require additional fields (national ID, phone, email, address) and route ambiguous cases to review or step-up verification.
eCBSV “No Match”	eCBSV matching can be strict on name/DOB formatting and consent requirements.	Confirm consent requirements are met and resubmit with exact legal name and DOB formatting. Route to fallback verification when needed.

How to debug

Use eval_id to trace the evaluation in the RiskOS Dashboard and logs.
Review data_enrichments[] results and status_code values to identify partial failures or missing modules.
Confirm required inputs were present for the workflow and any feature-gated sources (for example, eCBSV).
Use reasonCodes, tags, and review_queues to understand how the workflow routed the case. Definitions and context are available in the RiskOS Dashboard.
Review fieldValidations to identify which inputs matched or did not match, and reprompt or step up verification when critical fields fail validation.

Fallback strategies

If Verify or Verify Plus does not yield a confident match:

Enable partial match tolerance. Accept lower recall thresholds in low-risk flows (e.g., phone and name match but address fails).
Use secondary enrichments. Chain to eCBSV, Document Verification, or Graph modules for additional confidence.
Retry with normalized inputs. Reformat fields (e.g., remove accents, casing issues, redundant whitespace) and re-evaluate.
Escalate to review. Use tags or review_queues to route inconclusive results to human analysts.

Escalation path

For production-impacting issues or complex edge cases:

Reproduce in Sandbox when possible.
Capture identifiers: eval_id, workflow name, and the full request/response (with sensitive data handled per your logging policy).
Contact Socure Support and include expected vs. actual outcome and any relevant screenshots or logs.
For urgent issues, escalate through your designated support/escalation contacts.

Known limitations

Availability and response fields vary by provisioning. Verify Plus and certain datasets may require additional enablement.
Coverage varies by region and identity profile. Some users may have limited data availability depending on local sources and recency.
Input normalization matters. Inconsistent formatting (Unicode, whitespace, punctuation) can affect match outcomes—normalize inputs consistently before submission.
High-signal transactions may return many reason codes. Use workflow routing and tags to avoid overfitting to individual codes.

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

FAQs

General product behavior

What’s the difference between Verify and Verify Plus?

Verify (kyc) performs field-level identity validation across supported global markets.

Verify Plus (kycplus) is available for U.S. identities and returns expanded identity resolution results, including matched identity attributes and source attribution, when provisioned.

What data is required to run Verify Plus?

Verify Plus requires a combination of identity inputs such as name, date of birth, national ID (or last four digits where applicable), address, phone, or email.

Providing multiple corroborating identity inputs improves match confidence and coverage. Required inputs depend on workflow configuration and provisioning.

Can I use Verify Plus outside the U.S.?

No. Verify Plus is limited to U.S. identities. For international workflows, use Verify (kyc) where supported.

Integration and input formatting

What’s the minimum input needed to get a decision?

RiskOS™ attempts to resolve identity using the strongest combination of inputs available based on workflow configuration.

Commonly used input combinations include:

National ID (where permitted)
Name + date of birth
Name + phone
Name + address
Date of birth + phone

Providing additional identity inputs generally improves resolution quality, but required fields vary by workflow and region.

What happens if my input is missing or malformed?

If required inputs are missing or do not meet formatting requirements, certain modules (for example, Verify Plus) may not run.

Malformed fields can result in enrichment errors or cause workflows to follow alternate routing paths based on configuration.

Can I pass special characters or Unicode?

Yes. Inputs should be UTF-8 encoded and consistently normalized.

Unescaped control characters or inconsistent formatting may result in validation or matching issues.

Output and match interpretation

How should I interpret match indicators?

Verify and Verify Plus return per-field validation results that indicate whether submitted inputs met configured match criteria.

These values are used internally by RiskOS™ workflows to determine routing and outcomes and should not be treated as probabilistic risk scores or hard-coded thresholds.

How should I use reason codes?

Reason codes provide additional context associated with an evaluation outcome. They are informational and are already reflected in the final decision.

Definitions and detailed interpretation are available in the RiskOS™ Dashboard and may vary by workflow and provisioning.

What does sourceAttribution tell me?

Source attribution indicates the categories of data that contributed to the identity resolution process (for example, credit or government data).

It does not expose individual data sources or weighting logic.

Why is bestMatchedEntity missing?

If no identity record meets the configured resolution criteria, a matched entity may not be returned.

Verify that submitted inputs are complete, accurate, and formatted correctly, and review workflow routing behavior in the RiskOS™ Dashboard.

Retry and fallback

What should I do if no match is returned?

Common next steps include:

Retry with normalized inputs (consistent casing, spacing, and formatting)
Provide additional identity inputs when available
Route to secondary verification methods such as Document Verification or manual review, based on your workflow design

Can I retry the same evaluation?

You can submit a new evaluation request with the same inputs.

In production environments, repeated retries with unchanged input are discouraged. Use the Sandbox environment to validate test cases and workflow behavior.

Debugging and escalation

How do I debug a failed enrichment or incomplete match?

Use eval_id to trace execution in the RiskOS™ Dashboard and logs
Review enrichment execution status and confirm required inputs were present
Inspect reason codes, workflow tags, and routing outcomes to understand how the evaluation was processed
Confirm feature-gated modules (for example, Verify Plus) are provisioned and enabled for the workflow

When should I escalate?

Escalate when:

An expected enrichment does not run despite sufficient input
Outcomes are inconsistent with workflow configuration
Expected test cases produce unexpected routing results

When escalating, provide:

eval_id
referenceId (if applicable)
Workflow name
Request and response payloads (handled per your data-handling policies)
Reproduction steps or logs, if available

Product limitations

Can I use Verify Plus in international workflows?

No. Verify Plus is limited to U.S. identities. For international coverage, use Verify (kyc) where supported.

Can I use this for document or biometric verification?

No. Verify and Verify Plus do not perform document or biometric verification.

Use Socure Predictive Document Verification for document and facial biometric workflows.

Can I determine if someone is a politically exposed person (PEP)?

No. PEP and sanctions screening are handled by the Watchlist module.

How fresh are the data sources used?

Source freshness varies by data category and provisioning.

You can inspect contributing source categories via sourceAttribution, but individual source timestamps are not exposed.