Integrate Socure Verify

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the Verify or Verify Plus enrichment.
• Regional support coverage for the Verify or Verify Plus enrichment.

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

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

• Real customer data
• API usage charges apply
• Connects to live data services

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. Send a POST request to /api/evaluation with identity data.
2. Socure runs the request through configured RiskOS™ workflow with tailored enrichments.
3. Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
4. Apply your routing logic based on the result.

Common integration patterns

The table below outlines common integration patterns for Socure Verify and Verify Plus. Fields vary by country based on locally accepted identity documents and regulatory standards. Contact your account executive for country-specific details.

Note:

📘

Verify Plus is only available in the United States. For international workflows, use Verify.

Example frontend input form (mapped to /api/evaluation payload)

This example screen shows how a mobile app might capture user information during onboarding before triggering a RiskOS™ /api/evaluation request.

Each field maps to required parameters in the data.individual object:

• First Name → given_name
• Last Name → family_name
• Date of Birth → date_of_birth
• National ID → national_id

You can configure which fields are required per workflow by adjusting module-level match logic in RiskOS™.

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

JSONcURL

{
  "id": "APP-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jonathan",
      "family_name": "Reyes",
      "national_id": "1234",
      "phone_number": "+639171234567",
      "email": "jonathan.reyes1979@gmail.com",
      "date_of_birth": "1979-07-30",
      "ip_address": "203.87.128.100",
      "address": {
        "line_1": "123 Rizal Avenue",
        "locality": "Portland",
        "major_admin_division": "OR",
        "postal_code": "85142",
        "country": "US"
      }
    }
  }
}

curl --location '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-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jonathan",
      "family_name": "Reyes",
      "national_id": "1234",
      "phone_number": "+639171234567",
      "email": "jonathan.reyes1979@gmail.com",
      "date_of_birth": "1979-07-30",
      "ip_address": "203.87.128.100",
      "address": {
        "street_address": "123 Rizal Avenue",
        "locality": "Portland",
        "major_admin_division": "OR",
        "postal_code": "85142",
        "country": "US"
      }
    }
  }
}'

Request schema

Top-level fields

individual fields

Validation rules & accuracy guidance

These rules ensure RiskOS™ has enough information to perform a reliable identity match.

Identity Verification Requirements

At least ONE of the following combinations must be provided:

• Name + Date of Birth
  • given_name + family_name + date_of_birth
• Name + Phone
  • given_name + family_name + phone_number
• Name + Address
  • given_name + family_name + address
• National ID (Standalone)
  • national_id (can be provided alone or with other fields)
  • U.S.: Full SSN/TIN or last 4 digits of SSN
  • Other countries: Full government-issued ID

Accuracy Guidance

More PII fields = higher matching accuracy and coverage. Recommended combinations:

• Best Accuracy
  • national_id (full SSN/TIN) + given_name / family_name + date_of_birth + phone_number + address
• Better Accuracy
  • given_name / family_name + date_of_birth + phone_number + address
• Good Accuracy
  • given_name / family_name + any two additional fields
• Minimum Viable
  • given_name / family_name + one additional field
  • ORnational_id alone (last 4 SSN requires additional fields for verification)
  • ORphone_number + date_of_birth

address

Example response

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

JSON

{
  "id": "APP-987654",
  "workflow": "api_individual_onboarding",
  "workflow_id": "fae769dc-832f-4619-a386-54873b8861e5",
  "workflow_version": "65.1.0",
  "eval_source": "API",
  "eval_id": "c9e53a0f-35f4-4d18-bf26-ec1788c9f47a",
  "eval_start_time": "2025-11-17T20:03:49.123613925Z",
  "eval_end_time": "2025-11-17T20:03:49.686548734Z",
  "decision": "ACCEPT",
  "decision_at": "2025-11-17T20:03:49.686428264Z",
  "status": "CLOSED",
  "sub_status": "Accept",
  "tags": [
    "low_id_coverage",
    "manual_review_required"
  ],
  "notes": "",
  "review_queues": [
    "kyc-apac-philippines"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "Socure KYC PROD SBX",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "city": "Danbury",
        "consentTimestamp": "2025-11-17T20:03:48.252000Z",
        "country": "US",
        "countryOfOrigin": "US",
        "customerUserId": "custom-customer_user_id",
        "date_of_birth": "1958-01-31",
        "firstName": "Ananda",
        "gender": "Male",
        "homeNumber": "+1-203-798-6508",
        "mobileNumber": "+12037986508",
        "modules": [
          "kyc"
        ],
        "nationalId": "700-01-3784",
        "parentTxnId": "bcbb1fef-c125-42ea-a059-aee00381835f",
        "physicalAddress": "2 Moran Ave",
        "physicalAddress2": "Address line 2",
        "riskOSId": "Effectiv-Test-kyc-1763409828252",
        "state": "CT",
        "surName": "test",
        "userConsent": true,
        "userId": "data-individual-id",
        "workflow": "api_individual_onboarding",
        "zip": "06810"
      },
      "response": {
        "kyc": {
          "socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
          "nationalId": "786-00-1234",
          "reasonCodes": [
            "I919"
          ],
          "fieldValidations": {
            "city": 0.99,
            "dob": 0.99,
            "driverLicense": 0.99,
            "email": 0.99,
            "firstName": 0.99,
            "mobileNumber": 0.99,
            "ssn": 0.99,
            "state": 0.99,
            "streetAddress": 0.99,
            "surName": 0.99,
            "zip": 0.99
          },
          "sourceAttribution": [
            "Credit",
            "Government",
            "Education"
          ],
          "transactionScope": "international",
          "callType": "2X2",
          "matchCounts": {
            "tradelines": 3
          },
          "fieldSourceAttribution": {
            "firstName": ["Government"],
            "surName": ["Government"],
            "ssn": ["Government"]
          }
        },
        "referenceId": "8d92942e-af40-47b3-9b19-3f13456f401b",
        "customerProfile": {
          "userId": "data-individual-id",
          "customerUserId": "custom-customer_user_id"
        }
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "CONDITION": true,
    "socure_kyc_response": {
      "__third_party_name__": "Socure KYC PROD SBX",
      "kyc": {
        "socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
        "nationalId": "786-00-1234",
        "reasonCodes": [
          "I919"
        ],
        "fieldValidations": {
          "city": 0.99,
          "dob": 0.99,
          "driverLicense": 0.99,
          "email": 0.99,
          "firstName": 0.99,
          "mobileNumber": 0.99,
          "ssn": 0.99,
          "state": 0.99,
          "streetAddress": 0.99,
          "surName": 0.99,
          "zip": 0.99
        },
        "sourceAttribution": [
          "Credit",
          "Government",
          "Education"
        ],
        "transactionScope": "international",
        "callType": "2X2",
        "matchCounts": {
          "tradelines": 3
        },
        "fieldSourceAttribution": {
          "firstName": ["Government"],
          "surName": ["Government"],
          "ssn": ["Government"]
        }
      },
      "referenceId": "8d92942e-af40-47b3-9b19-3f13456f401b",
      "customerProfile": {
        "userId": "data-individual-id",
        "customerUserId": "custom-customer_user_id"
      }
    }
  },
  "aggregations": { },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

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

Decision and routing (primary control signals)

These fields describe the outcome of an evaluation and any routing applied by the workflow.

"low_id_coverage",
"manual_review_required"

]| |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-apac-philippines" ]| |notes| String | Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. |""` |

Evaluation lifecycle and status

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

Identifiers and traceability

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

Execution context

These fields provide timing and environment context for the evaluation.

Enrichment results

Enrichment outputs are returned in the data_enrichments array. Each object corresponds to a module executed as part of the Consumer Onboarding workflow.