Update an Evaluation

API Evaluation Request Schema

Required Attributes

• eval_id (uuid)
  The system-generated unique ID for the evaluation. Capture this value from the initial POST /api/evaluation response.

• X-API-Version (string)
  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 (string, enum, required)
  Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist.

  • Allowed: consumer_onboarding

• 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.

• timestamp (date-time, required)
  The timestamp indicating when the evaluation was initiated, in ISO 8601 / RFC 3339 format.

• customer_metadata (object | null)
  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.

Actions

• actions (object)
  A top-level container for instructions that modify the lifecycle of the current evaluation session.

Data Payload

• data (object, required)
  The main payload for the Consumer Onboarding workflow.

• Response Structure

  • id (string)
    The client-defined request identifier, echoed back in the response.
  • eval_id (uuid)
    A unique identifier generated by RiskOS™ for this evaluation. Required for all GET and PATCH operations.
  • workflow (string)
    Your environment-specific workflow executed for this evaluation.
  • eval_status (string)
    The current lifecycle state of the evaluation — for example, evaluation_in_progress, evaluation_completed, or evaluation_paused.
  • decision (string, enum)
    The final outcome of the evaluation. Possible values are ACCEPT, REVIEW, and REJECT.
  • eval_start_time (date-time)
    RFC 3339 timestamp for when RiskOS™ started processing the evaluation.
  • eval_end_time (date-time)
    RFC 3339 timestamp for when RiskOS™ finished processing the evaluation.
  • tags (array of strings)
    Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes.
  • notes (string)
    Freeform text field for analyst or system comments about the evaluation.
  • data_enrichments (array of objects)
    A collection of external enrichment results generated during the workflow.

Sample Request

curl --request PATCH \
     --url https://riskos.socure.com/api/evaluation/eval_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{\n  "id": "onb-12345",\n  "timestamp": "2023-12-01T08:15:30.456Z",\n  "workflow": "consumer_onboarding",\n  "data": {\n    "individual": {\n      "email": "updated.email@example.com"\n    }\n  }\n}'

Sample Response

{\n  "id": "onb-12345",\n  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",\n  "workflow": "consumer_onboarding",\n  "eval_status": "evaluation_in_progress",\n  "decision": "REVIEW",\n  "score": 51,\n  "eval_start_time": "2024-12-02T10:30:00.123Z",\n  "eval_end_time": "2024-12-02T10:32:00.456Z",\n  "tags": [\n    "none"\n  ],\n  "review_queues": [\n    "Default Queue"\n  ],\n  "data_enrichments": [\n    {\n      "enrichment_name": "Socure Phone Risk",\n      "enrichment_provider": "Socure",\n      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",\n      "status_code": 200,\n      "response": {\n        "referenceId": "68bb36f1-7e32-4600-bebf-26a6cdd39f8b"\n      },\n      "is_source_cache": false,\n      "total_attempts": 1\n    }\n  ]\n}