Integration Guide

CNAM API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the CNAM enrichment. You’ll learn how to send phone number data, parse the caller name response, and apply decision logic to support onboarding, fraud detection, and compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the CNAM enrichment.

Regional support coverage for the CNAM enrichment (US phone numbers only).

Choose your environment

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

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

No real customer data
Free testing environment
Unlimited API calls

Get an API key

In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.
Copy your API key securely.

How it works

Add CNAM as an enrichment in your RiskOS™ workflow.
Send a POST request to /api/evaluation with the phone number (E.164 format).
Socure queries telecom CNAM sources and returns registered caller identity details.
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

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.	`"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).	`"+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.

decision values are workflow-specific and may differ from the examples shown in this guide.

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.	`["name_phone_mismatch"]`
`review_queues`	Array of Strings	Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.	`["kyc-us"]`
`notes`	String	Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context.	`"CNAM result requires verification"`

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Field	Type	Description	Example
`eval_status`	String (enum)	Indicates the current state of an evaluation in RiskOS™. Possible values: • `evaluation_completed` • `evaluation_paused` • `evaluation_in_progress`	`"evaluation_completed"`
`status`	String (enum)	Indicates the current state of an evaluation or case. Possible values: • `OPEN` • `CLOSED`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"Under Review"`

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Field	Type	Description	Example
`id`	String (UUID or custom string)	Your evaluation identifier within RiskOS™. Note: This is customer-generated.	`"APP-123456"`
`eval_id`	String (UUID)	RiskOS-generated unique identifier for the evaluation.	`"91a6a0a8-5c4a-4f5a-93f0-1f3e78e2f9c1"`
`workflow`	String	Name of the workflow executed.	`"consumer_onboarding"`
`workflow_id`	String (UUID)	Unique identifier for the workflow run.	`"e87f4f3b-9d6c-4e3b-bdf6-8df94c3d8a01"`
`workflow_version`	String	Version of the executed workflow.	`"41.2.0"`

Execution context

These fields provide timing and environment context for the evaluation.

Field	Type	Description	Example
`eval_source`	String (enum)	Indicates where the evaluation was initiated from. Possible values: • `API`: Request submitted via the Evaluation API. • `Dashboard`: Case created or evaluated through the RiskOS™ Dashboard.	`"API"`
`eval_start_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring.	`"2025-09-30T08:15:30.982Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time.	`"2025-09-30T08:15:31.215Z"`
`environment_name`	String	Indicates which environment the evaluation ran in. Typically `Sandbox` for testing or `Production` for live traffic.	`"Sandbox"`

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

Field	Type	Description	Example
`enrichment_name`	String	Product name.	`"Socure CNAM`
`enrichment_endpoint`	String (URL)	Endpoint invoked.	`"https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam"`
`enrichment_provider`	String	Provider.	`"Socure"`
`status_code`	Integer	HTTP status code.	`200`
`request`	Object	Payload sent to provider.	See `request` fields below.
`response`	Object	Payload returned by provider.	See `response` fields below.
`is_source_cache`	Boolean	Response served from cache.	`false`
`total_attempts`	Integer	Number of attempts.	`1`

`request` fields

Field	Type	Description	Example
`phoneNumber`	String	Phone number submitted.	`"+13475550100"`

`response` fields

Field	Type	Description	Example
`callerName`	String	Registered name associated with the phone number.	`"Dwayne Denver"`
`callerType`	String	Either `CONSUMER` or `BUSINESS`.	`"CONSUMER"`
`countryCode`	String	Two-letter ISO country code.	`"US"`
`phoneNumber`	String	Queried phone number in E.164 format.	`"+13475550100"`
`valid`	Boolean	Whether the number is recognized as valid.	`true`

Test in Sandbox

You can simulate almost any identity scenario using our Test Personas JSON file. Each entry includes a realistic, sandbox-only identity and a ready-to-use API request payload. Many entries also include the expected response to help you validate your /api/evaluation integration before going live.

Endpoint: POST /api/evaluation
Base URL (Sandbox): https://riskos.sandbox.socure.com/api/evaluation
Auth: Authorization: Bearer YOUR_SANDBOX_KEY

The following table lists all supported CNAM test personas. Detailed request/response examples are provided below.

Test Case	Request: `phone_number`	Response: `callerName`	Response: `callerType`	Response: `countryCode`	Response: `valid`
1	`+14155551212`	`John Doe`	`Consumer`	`US`	`true`
2	`+14155551213`	`Jane Doe`	`Consumer`	`US`	`true`
3	`+14155551214`	`John Smith`	`Consumer`	`US`	`true`
4	`+14155551215`	`Jane Smith`	`Consumer`	`US`	`true`
5	`+14155551216`	`John Johnson`	`Consumer`	`US`	`true`
6	`+14155551217`	`Jane Johnson`	`Consumer`	`US`	`true`
7	`+14155551218`	`John Brown`	`Consumer`	`US`	`true`
8	`+14155551219`	`Jane Brown`	`Consumer`	`US`	`true`

Test case 1 — John Doe (+14155551212)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551212"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551212",
        "transactionId": "0aa783e6-c7ed-44ec-a069-2f4680d91dd2"
      },
      "response": {
        "callerName": "John Doe",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551212",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "John Doe",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551212",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 2 — Jane Doe (+14155551213)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551213"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551213",
        "transactionId": "f5b427d6-862f-4a4b-9c6e-6bfbbb2f28ae"
      },
      "response": {
        "callerName": "Jane Doe",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551213",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "Jane Doe",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551213",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 3 — John Smith (+14155551214)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551214"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551214",
        "transactionId": "c3ff2626-ff4c-4b2a-bcd9-714b34a612cb"
      },
      "response": {
        "callerName": "John Smith",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551214",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "John Smith",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551214",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 4 — Jane Smith (+14155551215)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551215"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551215",
        "transactionId": "7d6611a0-aff7-428d-b65e-25a32731165b"
      },
      "response": {
        "callerName": "Jane Smith",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551215",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "Jane Smith",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551215",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 5 — John Johnson(+14155551216)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551216"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551216",
        "transactionId": "e270c7d2-36dd-4011-b913-fbd9e3f8960c"
      },
      "response": {
        "callerName": "John Johnson",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551216",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "John Johnson",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551216",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 6 — Jane Johnson (+14155551217)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551217"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551217",
        "transactionId": "22dce588-3245-49ee-be20-32e55300955a"
      },
      "response": {
        "callerName": "Jane Johnson",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551217",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "Jane Johnson",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551217",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 7 — John Brown (+14155551218)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551218"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551218",
        "transactionId": "c5c9da0c-8710-49ce-8a6d-560e874b05ac"
      },
      "response": {
        "callerName": "John Brown",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551218",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "John Brown",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551218",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Test case 8 — Jane Brown (+14155551219)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155551219"
      }
    }
  }'

{
  "data_enrichments": [
    {
      "enrichment_name": "Socure CNAM",
      "enrichment_endpoint": "https://mfa-orchestrator-service.webapps.us-east-1.prod.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNAM",
      "status_code": 200,
      "request": {
        "phoneNumber": "+14155551219",
        "transactionId": "5e3e8315-0fe3-4233-9f7f-93b6b6145257"
      },
      "response": {
        "callerName": "Jane Brown",
        "callerType": "Consumer",
        "countryCode": "US",
        "phoneNumber": "+14155551219",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "socure_cnam_response": {
      "__third_party_name__": "Socure CNAM",
      "callerName": "Jane Brown",
      "callerType": "Consumer",
      "countryCode": "US",
      "phoneNumber": "+14155551219",
      "valid": true
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Best practices for integration and maintenance

Always validate phone_number inputs in E.164 format.
Use sandbox mode and known test numbers during QA.
Log CNAM responses for audit trails.
Apply routing when CNAM mismatches the user-provided name.
Monitor coverage variations (especially VoIP lines).

Validation checklist

Test coverage

Known valid numbers → PASS

Invalid or unrecognized numbers → FAIL or REVIEW

Schema and error handling

Fields match schema across environments

Errors are structured and retryable

Logging and observability

Log full request/response with correlation IDs

Redact API keys and secrets