Troubleshooting and FAQs
Learn how to test, debug, and optimize your integration using Caller ID Name (CNAM) in RiskOS™.
Common errors
The table below outlines common errors that may occur when using Caller ID Name (CNAM) in RiskOS™. These issues can result from configuration gaps, carrier limitations, or outdated CNAM data. Understanding these patterns can help you fine-tune workflows, reduce false positives, and apply appropriate fallback strategies.
| Issue | Explanation | Suggested fix |
|---|---|---|
| CNAM not available in workflow | CNAM may not be enabled for your account. | Contact your Account Manager to have CNAM enabled. |
| Invalid API key error | The API key provided is incorrect, malformed, or expired. | Confirm you are using the correct RiskOS™ API key. Remove typos, extra spaces, or old keys. |
Empty or missing callerName | Some carriers do not support CNAM; mobile or VoIP numbers may not return it. | This is expected in limited coverage areas. Use fallback strategies when caller name is missing. |
Incorrect or unexpected callerName | CNAM databases may be outdated or differ across providers. | Cross-check CNAM with other RiskOS™ enrichments or alternate data sources. |
FAQs
General product behavior
How is CNAM data sourced?
CNAM data is pulled from telecom industry Line Information Databases (LIDBs) managed by carriers and aggregators.
Coverage varies depending on carrier and phone type (landline, VoIP, mobile), so not all numbers will return a caller name.
How is CNAM used in RiskOS™?
CNAM is available as an enrichment step in RiskOS™ workflows.
- It cross-checks the name a user provides against the registered name for their phone number.
- Mismatches can indicate potential fraud.
- Once enabled, CNAM results can be referenced by subsequent workflow steps and decision logic.
What request parameters are needed for CNAM?
The only required parameter is phone_number in E.164 format (e.g., +13475550100).
It can be placed in either the individual or business JSON object in the request payload.
Can I use international phone numbers with CNAM?
No. CNAM is limited to U.S. and Canadian phone numbers. International numbers are not supported.
Does phone number formatting matter in the API call?
Yes. Phone numbers must be in E.164 format (e.g., +15555551234).
Omitting the plus (+) can cause lookup failures. RiskOS™ has some fallbacks, but correct formatting is strongly recommended.
Are there known limitations or risks with CNAM?
- Only supported in the U.S. and Canada
- Not available for unregistered numbers or numbers with carrier-level CNAM blocking
- Should not be used as sole proof of ownership or association
How can I test CNAM functionality in the sandbox?
RiskOS™ sandbox supports test cases with predictable results.
- Example: For
+1-415-555-1212, the sandbox returns"John Doe". - If you see a
404error:- Confirm number formatting
- Ensure API keys are valid for the correct environment
Is CNAM available as a standalone service?
No. CNAM is not sold as a standalone Socure product.
It is offered as an enrichment, often included in prefill or identity verification bundles.
Who can I contact for help with CNAM provisioning or troubleshooting?
- Account Manager → Enablement and workflow integration
- Socure Support / Solution Consultant → Technical issues or endpoint troubleshooting
Updated 10 days ago