Start an Evaluation

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

{
  "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

{
  "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"
}