## Overview

This guide covers the system integration for Consumer Onboarding: connecting your frontend and backend to the Evaluation API, submitting requests, and acting on decisions.

For workflow configuration and enrichment setup, see [Configure the Workflow](https://help.socure.com/riskos/docs/configure-consumer-onboarding-workflow). For routing logic, DocV step-ups, and review flows, see [Handle Review & Step-Up Flows](https://help.socure.com/riskos/docs/handle-consumer-onboarding-review-step-up-flows).

## System architecture

```
RiskOS™Your BackendDigital Intelligence SDKClient AppRiskOS™Your BackendDigital Intelligence SDKClient Appalt[ACCEPT][REJECT][REVIEW / Step-Up]Initialize SDKdi_session_tokenSubmit PII + di_session_tokenPOST /api/evaluationDecision responseContinue onboardingDeny or fallbackTrigger DocV or manual reviewFinal decision (webhook)
```

## Integration flow

1. **Collect the Digital Intelligence session token** on the client. This solution uses the [Digital Intelligence SDK](https://help.socure.com/riskos/docs/digital-intelligence-sdks) for device collection.
2. **Gather identity data** from the consumer (name, date of birth, SSN, address, phone, email).
3. **Submit a `POST /api/evaluation`** request from your backend with the collected data.
4. **Act on the `decision` field** in the response to route the consumer.
5. **Handle verification and review outcomes** if the workflow triggers a step-up such as OTP, Predictive DocV, or manual review. See [Handle Review & Step-Up Flows](https://help.socure.com/riskos/docs/handle-consumer-onboarding-review-step-up-flows).

## Required components

A [configured Consumer Onboarding workflow](https://help.socure.com/riskos/docs/configure-consumer-onboarding-workflow).

Integration with the [Digital Intelligence SDK](https://help.socure.com/riskos/docs/digital-intelligence-sdks) to collect the `di_session_token`.

Integration with the [Predictive DocV SDK](https://help.socure.com/riskos/docs/docv-sdks) if your workflow uses document verification step-ups.

A RiskOS™ API key from [Developer Workbench > API Keys](https://riskos.sandbox.socure.com/developers/key-management) in the Dashboard.

A [webhook endpoint](https://help.socure.com/riskos/docs/webhooks) to receive results from asynchronous verification and review flows such as Predictive DocV.

## Endpoint

HTTP

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

HTTP

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

Include your API key in the `Authorization` header:

HTTP

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
```

## Example request

JSON

```json
{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "timestamp": "2025-05-02T12:44:22.059Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "id": "username",
      "given_name": "Franky",
      "family_name": "Valley",
      "national_id": "555667772",
      "date_of_birth": "1992-03-11",
      "email": "frankeyV@test.com",
      "phone_number": "16673681976",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 2B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "additional_context": {
        "disclosure_purpose": "GLBA_502(e)"
      },
      "di_session_token": "eyJraWQiOi_di_token",
      "docv": {
        "config": {
          "send_message": true
        }
      }
    },
    "ip_address": "203.0.113.10"
  }
}
```

## Request fields

### 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. | `"a86580cc-1733-4188-86b5-717166e1db8c"` |
| `timestamp` | String `<Date-Time>` | Required | RFC 3339 timestamp indicating when the evaluation request was initiated by your system. | `"2025-05-02T12:44:22.059Z"` |
| `workflow` | String | Required | Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > **Developer Workbench** > **Integration Checklist**. | `"consumer_onboarding"` |

### Individual fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Required | Consumer's first/given name (max 240 characters). | `"Franky"` |
| `family_name` | String | Required | Consumer's last/family name (max 240 characters). | `"Valley"` |
| `national_id` | String | Required | National identifier such as SSN, SIN, or equivalent, depending on geography. | `"555667772"` |
| `date_of_birth` | String | Required | Consumer's date of birth in ISO 8601 format (`YYYY-MM-DD`). | `"1992-03-11"` |
| `email` | String | Required | Consumer's email address (must be a valid email format). | `"frankeyV@test.com"` |
| `phone_number` | String | Required | Consumer's phone number. The API expects **E.164 format** but tolerates hyphens and spaces for user convenience. | `"16673681976"` |
| `di_session_token` | String (UUID) | Required | Token from the Digital Intelligence SDK that links the device session. Must be generated client-side before submitting the evaluation. | `"eyJraWQiOi_di_token"` |

### Address fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Optional | The first line of the consumer's address. | `"742 Evergreen Terrace"` |
| `line_2` | String | Optional | An optional second line for the address, such as apartment number, suite, or building landmarks. | `"Apt 2B"` |
| `locality` | String | Optional | City, town, or village name where the consumer resides. | `"Springfield"` |
| `major_admin_division` | String | Optional | The state, province, or region where the consumer resides. | `"IL"` |
| `country` | String | Optional | The country where the consumer resides, specified in **ISO 3166-1 alpha-2 country code** format. | `"US"` |
| `postal_code` | String | Optional | The consumer's ZIP code, postal code, or equivalent regional identifier for mail delivery. | `"62704"` |

### Additional context fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `disclosure_purpose` | String | Conditional | Disclosure for running Sigma First-Party Fraud product. | `"GLBA_502(e)"` |

### Predictive DocV fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `docv` | Object | Conditional | Configuration object used when the workflow escalates an applicant to Predictive DocV for document verification and biometric review. | `{ "config": { "send_message": true } }` |

## Handling responses

### Decision routing

| Decision | Action |
| --- | --- |
| `ACCEPT` | Continue onboarding |
| `REJECT` | Deny the application or route to a fallback flow |
| `REVIEW` | Trigger a step-up (DocV, manual review) depending on workflow configuration |

Use the `decision` field as your primary control signal. Do not use `status`, `sub_status`, or `eval_status` for business decisions — those fields describe evaluation lifecycle state only.

### Example response

Example response (truncated)

```json
{
  "id": "895dc35b-cee7-4f14-af06-6e26482178f8",
  "workflow": "consumer_onboarding",
  "eval_id": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "eval_status": "evaluation_completed",
  "score": 11,
  "data_enrichments": [
    {
      "enrichment_name": "Socure Digital Intelligence",
      "status_code": 200
    },
    {
      "enrichment_name": "Socure Verify Plus",
      "status_code": 200
    },
    {
      "enrichment_name": "Socure Global Watchlist Plus",
      "status_code": 200
    }
  ]
}
```

### Key response fields

| Area | Fields | Purpose |
| --- | --- | --- |
| **Decision and routing** | `decision`, `tags`, `review_queues`, `score` | Primary signals for application logic and secondary routing |
| **Traceability** | `id`, `eval_id` | Persist for correlation across API calls, logs, webhooks, and support |
| **Enrichment results** | `data_enrichments[]` | Module-specific scores, reason codes, and signals |
| **Workflow context** | `workflow`, `workflow_id`, `workflow_version` | Debugging and version tracking |
| **Lifecycle** | `eval_status`, `status`, `sub_status` | Monitoring and async flow tracking only |

For complete response field definitions, see the [Evaluation API Reference](https://help.socure.com/riskos/reference).