## X-API-Version

Specifies the API version used for the request. If omitted, the default version is used. Socure recommends pinning a version to avoid unexpected behavioral changes when new versions are released.

## workflow

Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist.

**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

Allowed:

`consumer_onboarding`

## id

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.

## timestamp

The timestamp indicating when the evaluation was initiated, in ISO 8601 / RFC 3339 format.

## customer_metadata

Optional, opaque JSON object echoed back unchanged on the response and at the top level of webhook callbacks — use it to route and correlate requests. Must be a JSON object of up to 200 characters total (the entire serialized JSON); larger payloads return `413 CUSTOMER_METADATA_TOO_LARGE`. Omit it or send `null` to skip. Don't include PII or secrets.

## data

The main payload for the Consumer Onboarding workflow.

### 200

The request was processed successfully.

#### data object

- **id** : The client-defined request identifier, echoed back in the response.
- **customer_metadata** : Optional, echoed back.
- **eval_id** : A unique identifier generated by RiskOS™ for this evaluation.
- **workflow** : Your environment-specific workflow executed for this evaluation.
- **workflow_id** : Unique identifier of the workflow definition that was executed.
- **eval_status** : The current lifecycle state of the evaluation.
- **decision** : The final outcome of the evaluation. Possible values: `ACCEPT`, `REVIEW`, `REJECT`.
- **decision_at** : RFC 3339 timestamp when the decision was finalized (UTC).
- **score** : If configured, provides an aggregate sum of the scores assigned to each matched step.
- **status** : Case-level status of the evaluation.
- **sub_status** : Provides additional detail about the evaluation status.
- **workflow_version** : Version of the executed workflow.
- **eval_source** : Indicates where the evaluation was initiated from.
- **eval_start_time** : RFC 3339 timestamp for when processing started.
- **eval_end_time** : RFC 3339 timestamp for when processing finished.
- **tags** : Array of labels applied during the workflow.
- **notes** : Freeform text field for comments about the evaluation.
- **review_queues** : Lists any manual review queues the evaluation was sent to.
- **data_enrichments** : A collection of external enrichment results generated during the workflow.

## Example Request

```json
{
  "id": "onb-12345",
  "timestamp": "2023-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "customer_metadata": {
    "service": "checkout-api",
    "business_unit": "consumer-lending",
    "internal_ref": "order-998877"
  },
  "data": {
    "line_of_business": "ACME Inc",
    "channel": "web",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "jane.smith@example.com",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "ip_address": "203.0.113.10"
  }
}
```

## Example Response

```json
{
  "id": "onb-12345",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "customer_metadata": {
    "service": "checkout-api",
    "business_unit": "consumer-lending",
    "internal_ref": "order-998877"
  },
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "eval_source": "API",
  "eval_start_time": "2024-12-02T10:28:24.456771162Z",
  "eval_end_time": "2024-12-02T10:29:10.999Z",
  "tags": ["High Risk","Bad Device"],
  "score": 146,
  "review_queues": [],
  "data_enrichments": [
    {"enrichment_name": "Deliver OTP SMS",
     "enrichment_endpoint": "https://idplus.dev.socure.com/api/1.0/otp/send",
     "enrichment_provider": "SocureOTP",
     "status_code": 200,
     "request": {"channel": "email","destination": "darshanvaishnav24@gmail.com"},
     "response": {"error": "","verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97"},
     "is_source_cache": false
    }
  ],
  "environment_name": "Sandbox"
}
```