## Before you start
Make sure your RiskOS™ environment is provisioned with:
- [A workflow configured](https://help.socure.com/riskos/docs/verify-riskos-setup#/) for the **Verify or Verify Plus** enrichment.
- [Regional support coverage](https://help.socure.com/riskos/docs/verify-overview#/) for the **Verify or Verify Plus** enrichment.
### Choose your environment
Start with **Sandbox** for development and testing, then move to **Production** for live applications.
```undefined
https://riskos.sandbox.socure.com/api/evaluation
```
- **No real customer data**
- **Free testing environment**
- **Unlimited API calls**
```undefined
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**](https://riskos.sandbox.socure.com/developers/api-keys).
2. Copy your API key securely.
1. In the Production RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandbox.socure.com/developers/api-keys).
2. 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.
| Module | Fields | Response |
| --- | --- | --- |
| kycplus | Name, DOB, national ID, address, email, phone | Full profile + audit trail |
| kyc | Name, DOB, national ID, address, email, phone | Match score + reason codes |
**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
```http
POST https://riskos.sandbox.socure.com/api/evaluation
```
```http
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:
```http
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
```json
{
"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
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
| 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-987654"` |
| `timestamp` | String | Required | Timestamp when evaluation was initiated. | `"2025-05-18T02:09:25Z"` |
| `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. | `"business_onboarding"` |
| `data` | Object | Required | Main payload containing business and individual information. | |
| →`individual` | Object | Required | Primary identity object containing individual's information. | See `individual` schema below. |
#### `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
- **OR**`national_id` alone (last 4 SSN requires additional fields for verification)
- **OR**`phone_number` + `date_of_birth`
| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Conditionally Required | First name of the individual. | `"Jonathan"` |
| `family_name` | String | Conditionally Required | Last name of the individual. | `"Reyes"` |
| `national_id` | String | Conditionally Required | Government-issued ID (last 4 SSN for U.S., full ID for others). | `"1234"` |
| `date_of_birth` | String | Conditionally Required | Date of birth in `YYYY-MM-DD` format. | `"1979-07-30"` |
| `email` | String | Optional | Individual’s email address. | `"jonathan.reyes1979@gmail.com"` |
| `phone_number` | String | Conditionally Required | Phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | `"+639171234567"` |
| `ip_address` | String | Optional | IP address in IPv4 or IPv6 format. | `"203.87.128.100"` |
| `address` | Object | Conditionally Required | Residential address of the individual. | See `address` schema below. |
#### `address`
| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Required | Street name and number. | `"123 Rizal Avenue"` |
| `locality` | String | Required | City or locality. | `"Portland"` |
| `major_admin_division` | String | Required | State, province, or region. | `"OR"` |
| `postal_code` | String | Required | Postal or ZIP code. | `"85142"` |
| `country` | String | Required | Two-letter ISO 3166-1 alpha-2 country code. | `"US"` |
## 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
```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
| 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)
These fields describe the outcome of an evaluation and any routing applied by the workflow.
| 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. | `"ACCEPT"` |
| `decision_at` | String | RFC 3339 timestamp when the decision was finalized. | `"2025-11-17T20:03:49.686428264Z"` |
| `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. | _Not returned_ |
| `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. | `[
"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.
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_status` | String enum | Internal RiskOS™ evaluation lifecycle state.
Possible values:
• `evaluation_completed`
• `evaluation_paused`
• `evaluation_in_progress` | `"evaluation_completed"` |
| `status` | String enum | Case-level status of the evaluation.
Possible values:
• `OPEN`
• `CLOSED` | `"CLOSED"` |
| `sub_status` | String | Provides additional detail about the evaluation status.
Example values:
• `Under Review`
• `Pending Verification`
• `Accept`
• `Reject` | `"Accept"` |
### 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-987654"` |
| `eval_id` | String (UUID) | RiskOS™-generated unique identifier for the evaluation. | `"c9e53a0f-35f4-4d18-bf26-ec1788c9f47a"` |
| `workflow` | String | Name of the workflow executed. | `"api_individual_onboarding"` |
| `workflow_id` | String (UUID) | Unique identifier for the workflow run. | `"fae769dc-832f-4619-a386-54873b8861e5"` |
| `workflow_version` | String | Version of the executed workflow. | `"65.1.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 | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring. | `"2025-11-17T20:03:49.123613925Z"` |
| `eval_end_time` | String | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time. | `"2025-11-17T20:03:49.686548734Z"` |
| `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. Each object corresponds to a module executed as part of the Consumer Onboarding workflow.
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `enrichment_name` | String | Name of the enrichment executed. | `"Socure KYC PROD SBX"` |
| `enrichment_provider` | String | Provider of the enrichment. | `"Socure"` |
| `status_code` | Integer | HTTP status returned by the enrichment call. | `200` |
| `request` | Object | Provider request payload (for observability and debugging). | See `request` schema below. |
| `response` | Object | Normalized enrichment response. | See `response` schema below. |
| `is_source_cache` | Boolean | Indicates whether cached data was used. | `false` |
| `total_attempts` | Integer | Number of attempts made to retrieve the data. | `1` |