Integrate Caller ID Name (CNAM)

Before you start

Make sure your RiskOS™ environment is provisioned with:

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

https://riskos.socure.com/api/evaluation

Get an API key

  1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  2. Copy your API key securely.

  3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  4. Copy your API key securely.

How it works

  1. Add CNAM as an enrichment in your RiskOS™ workflow.
  2. Send a POST request to /api/evaluation with the phone number (E.164 format).
  3. Socure queries telecom CNAM sources and returns registered caller identity details.
  4. Use CNAM results (e.g., callerName, callerType) to enhance decisioning and routing.

Common integration patterns

The table below outlines common CNAM use cases and expected outcomes.

Use Case Required Inputs Response Fields Example Outcome
Identity verification phone_number callerName, callerType Match user-provided vs. CNAM record
Fraud detection (VoIP mismatch) phone_number callerName, valid Flag when CNAM missing or invalid
Case management / audit trails phone_number callerName, countryCode Log CNAM results with evaluation

Start a new Risk Evaluation

Endpoint

SandboxProduction

POST https://riskos.sandbox.socure.com/api/evaluation

POST https://riskos.socure.com/api/evaluation

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Example request

{
  "id": "APP-12345",
  "timestamp": "2025-09-30T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "phone_number": "+14155551212"
    }
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "id": "APP-12345",
    "timestamp": "2025-09-30T08:15:30.456Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "phone_number": "+14155551212"
      }
    }
  }'

Request schema

Top-level fields

Field Type Required Description Example
id String Required Required, customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows. "APP-12345"
timestamp String Required RFC 3339 timestamp when the request was made. "2025-09-30T08:15:30.456Z"
workflow String Required RiskOS™ workflow name configured in your environment. Note: The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request. "consumer_onboarding"
data Object Required Main payload containing business and individual information See data schema below.
→individual Object Required Primary identity object containing individual's information.
→individual.phone_number String Required Phone number in E.164 format (U.S. only). The API expects the standard E.164 format (e.g., +12025550147) but tolerates hyphens and spaces for user convenience. "+14155551212"

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "data_enrichments":
  [
    {
      "enrichment_name": "SocureCNam",
      "enrichment_endpoint": "https://<your-domain>/api/2.0/cnam",
      "enrichment_provider": "SocureCNam",
      "status_code": 200,
      "request":
      {
        "phoneNumber": "+13475550100"
      },
      "response":
      {
        "callerName": "Dwayne Denver",
        "callerType": "CONSUMER",
        "countryCode": "US",
        "phoneNumber": "+13475550100",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ]
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Area Fields How to use it
Decision and routing decision, decision_at, tags, review_queues, notes, score Primary control signals. Branch application logic using decision. Use tags, queues, notes, and score for secondary routing, review, and explanation.
Module results Module-specific fields (for example: reasonCodes, scores, extracted attributes) Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit.
Identifiers and traceability id, eval_id Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
Enrichment execution data_enrichments[] (response, status_code, total_attempts, is_source_cache) Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
Workflow context workflow, workflow_id, workflow_version Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
Evaluation lifecycle eval_status, status, sub_status Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
Execution context eval_source, eval_start_time, eval_end_time, environment_name Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution.

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

Field Type Description Example
decision String (enum) Final evaluation result. Possible values: • ACCEPT • REVIEW • REJECT Note: The fields returned can be customized to fit your integration or business needs. "REVIEW"
decision_at String <Date-Time> RFC 3339 timestamp when the decision was finalized. "2025-09-30T08:15:31.102Z"
score Number If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary decision value. 0.87
tags Array of Strings Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. `[\