Handle Results

After you create a Hosted Flow evaluation, RiskOS™ returns an initial response that starts the hosted session. This response is used to launch the Hosted Flow and track the evaluation, but it does not represent the final onboarding outcome.

📘
Important:
The initial response is not the final decision. Always use the evaluation_completed webhook for the final result.

Initial response

What happens next

For Hosted Flow, the initial response typically includes:

decision: "REVIEW"
status: "ON_HOLD"
eval_status: "evaluation_paused"
redirect_uri

This indicates that:

The hosted session was created successfully
The evaluation is paused
User interaction is required to continue

What to do

When your application receives the response:

Persist the eval_id for tracking and correlation
Extract the redirect_uri
Redirect the user to the hosted experience
Wait for the webhook to deliver the final decision

Example response

{
  "id": "2e9347a5-1be2-48f7-b129-255209842afe",
  "workflow": "consumer_onboarding",
  "workflow_id": "7025fd0c-030f-4936-aac2-94d8add13eb2",
  "workflow_version": "10.40.0",
  "eval_source": "API",
  "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
  "eval_start_time": "2026-03-11T16:12:30.064687002Z",
  "eval_end_time": "2026-03-11T16:12:30.065465293Z",
  "decision": "REVIEW",
  "decision_at": "2026-03-11T16:12:30.065472733Z",
  "status": "ON_HOLD",
  "sub_status": "More information needed",
  "tags": [],
  "notes": "",
  "review_queues": [
    "Default Queue"
  ],
  "eval_status": "evaluation_paused",
  "environment_name": "Sandbox",
  "redirect_uri": "https://riskos.sandbox.socure.com/hosted/v2/35cf1009-c2c6-4cc2-b084-b5e469163542"
}

👍
Tip:
A "decision": "REVIEW" response includes the hosted redirect_uri. This URL is required to launch the hosted onboarding experience.

Key fields

For complete response field definitions, see the Evaluation API Reference.

Field	Description
`eval_id`	Unique identifier for the evaluation (persist this).
`decision`	Initial state (`REVIEW` is expected).
`status`	`ON_HOLD` means waiting for user interaction.
`eval_status`	`evaluation_paused` means the flow is in progress.
`redirect_uri`	URL to launch the Hosted Flow.

Receive the final decision (webhook)

After the Hosted Flow completes, RiskOS™ sends an evaluation_completed webhook to your configured webhook endpoint.

The final outcome is in:

data.decision

RiskOS™ responses include additional fields for enrichment results, workflow context, and observability.

Example webhook

{
  "event_type": "evaluation_completed",
  "event_id": "3b31289c-2d4a-4107-80bc-dda63031d5a0",
  "event_at": "2025-07-17T01:20:01Z",
  "data": {
    "eval_id": "11111111-2222-3333-4444-555555555555",
    "id": "client-transaction-12345",
    "workflow": "consumer_onboarding",
    "workflow_id": "5937a624-f298-452c-9169-ceeae9e66b74",
    "workflow_version": "1.0.0",
    "environment_name": "Sandbox",
    "eval_source": "API",
    "eval_start_time": "2025-07-17T01:18:27Z",
    "eval_end_time": "2025-07-17T01:20:01Z",
    "eval_status": "evaluation_completed",
    "decision": "ACCEPT",
    "decision_at": "2025-07-17T01:20:01Z",
    "status": "CLOSED",
    "sub_status": "Accept",
    "tags": [],
    "notes": "",
    "review_queues": [
      "Default Queue"
    ],
    "data_enrichments": [
      {
        "enrichment_name": "Socure Document Request - Default Flow",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
        "enrichment_provider": "SocureDocRequest",
        "status_code": 200,
        "response": {
          "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927cd",
          "status": "SESSION_COMPLETE",
          "data": {
            "docvTransactionToken": "7d6ad42b-f804-4255-b25e-268b8a77c86f",
            "url": "https://verify.socure.com/#/dv/7d6ad42b-f804-4255-b25e-268b8a77c86f"
          }
        }
      },
      {
        "enrichment_name": "Socure Document Verification",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
        "enrichment_provider": "Socure",
        "status_code": 200,
        "response": {
          "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927c",
          "documentVerification": {
            "decision": {
              "name": "standard",
              "value": "accept"
            },
            "reasonCodes": [
              "I831",
              "I836"
            ],
            "documentType": {
              "type": "Drivers License",
              "country": "USA",
              "state": "NY"
            },
            "documentData": {
              "firstName": "Test",
              "surName": "User",
              "fullName": "Test User",
              "dob": "1990-01-01",
              "documentNumber": "TST1234567",
              "expirationDate": "2030-01-01"
            }
          }
        }
      }
    ]
  }
}

Route the user based on the final decision

Because the evaluation completes asynchronously, your frontend should wait for your backend to persist the final decision before routing the user.

Expose the persisted decision from your backend to the frontend (for example, via a status endpoint), then handle routing as follows:

ACCEPT → Continue onboarding
REJECT → Route to fallback or denial flow
REVIEW → Route to manual review (if applicable)

One common approach is polling your backend until the stored decision is available.

if (data.decision === "ACCEPT") {
  router.push("/success");
}

if (data.decision === "REJECT") {
  router.push("/review");
}

📘
Note:
Do not use status or eval_status for business decisions.

Error handling

If the API returns an HTTP error (4xx or 5xx), your application should handle it before processing any evaluation logic.

Status code	Meaning	What to do
`400`	Bad request — missing or invalid fields	Check request body against required fields.
`401`	Unauthorized — invalid or missing API key	Verify your `Authorization` header.
`404`	Not found — invalid `eval_id` or endpoint	Confirm the `eval_id` and endpoint URL.
`429`	Rate limited	Back off and retry after the `Retry-After` header value.
`500`	Internal server error	Retry with exponential backoff (max three attempts).

For the full error schema and all error codes, see the Errors Reference.

Data handling

What to persist

Store these fields for tracking:

Field	Description
`id`	Unique identifier for the request
`eval_id`	Evaluation identifier
`decision`	Final decision outcome
`status`	Overall request status
`eval_status`	Evaluation processing status
`workflow`	Workflow name (optional)

Implementation flow

Start evaluation
    |
    v
Store `eval_id`
    |
    v
Redirect user to the Hosted Flow
    |
    v
Wait for webhook
    |
    v
Persist final `decision`
    |
    v
Route user based on outcome

Summary

The API response starts the session.
The user completes verification in the Hosted Flow.
The webhook delivers the final decision.
Your application should act only on the webhook result.