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:

1. Persist the eval_id for tracking and correlation
2. Extract the redirect_uri
3. Redirect the user to the hosted experience
4. Wait for the webhook to deliver the final decision

Example response

{
  "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "eval_status": "evaluation_paused",
  "redirect_uri": "https://riskos.sandbox.socure.com/hosted/xyz"
}

Key fields

Redirect the user

Immediately redirect the user to the redirect_uri.

During the hosted session, RiskOS™ handles:

• Identity data collection
• Fraud checks
• Watchlist screening
• Optional One-Time Passcode and Document Verification (DocV)

Your application does not collect PII during this step.

Web integration

If integrating in a web application, redirect the user to the hosted redirect_uri. You may open it in the same tab or a new tab.

window.location.href = hostedRedirectUri

iOS integration

Launch the RiskOS™ Hosted Flow using an in-app browser such as SFSafariViewController.

import SafariServices

let safariVC = SFSafariViewController(url: URL(string: hostedRedirectUri)!)
present(safariVC, animated: true)

Android

Launch the RiskOS™ Hosted Flow using Chrome Custom Tabs for a secure in-app browser experience.

val customTabsIntent = CustomTabsIntent.Builder().build()
customTabsIntent.launchUrl(this, Uri.parse(hostedRedirectUri))

Returning to your redirect_uri means the user experience is complete — not that the evaluation is finalized.

Receive the final decision

After the Hosted Flow completes, RiskOS™ sends an evaluation_completed webhook. For the full webhook payload schema and all available response fields, see the Evaluation API Reference.

The final outcome is in:

• data.decision

Example webhook

{
  "event_type": "evaluation_completed",
  "data": {
    "eval_id": "11111111-2222-3333-4444-555555555555",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "eval_status": "evaluation_completed"
  }
}

Handle the final decision

Because the evaluation completes asynchronously, your frontend should wait for your backend to persist the final decision, then route the user accordingly.

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

For a complete breakdown, see the Evaluation API Reference.

Routing logic

Your backend should expose the persisted decision to the frontend (for example, via a status endpoint).

• 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");
}

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.

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

Data handling

What to persist

Store these fields for tracking:

• id
• eval_id
• decision
• status
• eval_status
• workflow (optional)

Implementation flow

1. Start an evaluation.
2. Store the eval_id.
3. Redirect user to the Hosted Flow.
4. Wait for webhook.
5. Persist final decision.
6. 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.