Update an Evaluation

Use the PATCH /api/evaluation/{eval_id} endpoint to continue an evaluation after additional input is required.

This endpoint is used to:

• Submit a One-Time Passcode (OTP)
• Provide additional identity data
• Continue the evaluation after a step-up event

Overview

After the initial evaluation request, RiskOS™ may return a response with:

• decision = REVIEW
• status = ON_HOLD

This indicates that additional input is required to continue the evaluation.

Your application must collect the required input and submit it using PATCH /api/evaluation/{eval_id}.

When to use this endpoint

Use PATCH when the evaluation response indicates:

Endpoint

Start with Sandbox for development and testing, then move to Production for live applications.

PATCH https://riskos.sandbox.socure.com/api/evaluation/{eval_id}

PATCH https://riskos.socure.com/api/evaluation/{eval_id}

For full request and response schemas, see the Evaluation API Reference.

Key rules

• Always use the same eval_id returned from the initial request.
• Only include fields required for the current step.
• Do not resend previously submitted data unless updated.
• Treat each PATCH response as a new decision point.

Submit a One-Time Passcode

User interaction

When One-Time Passcode is required, your application must:

1. Prompt the user to enter a 6-digit One-Time Passcode
2. Submit the code using the PATCH endpoint

Example request

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/{eval_id}" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "otp": {
        "code": "123456"
      }
    }
  }'

Submit identity data

Submit full identity data to continue the evaluation after:

• One-Time Passcode succeeds
• Prefill is data shown
• Additional data is required

Data collection

Before submitting a PATCH request, your application must collect the required identity fields.

Prefill handling

If Prefill data is available:

• Display prefilled identity data to the user
• Collect any remaining fields

If Prefill data is not available:

• Display a blank form
• Collect all required fields

👍

Tip:

To improve match accuracy, collect a comprehensive set of identity fields.

Field requirements

Field restrictions

To prevent mismatches between Prefill and the final evaluation request, do not allow users to edit:

• date_of_birth
• phone_number
• address.country

Required fields

The following fields are required to continue the evaluation:

• given_name
• family_name
• address.country

Recommended fields (highest match accuracy)

• given_name
• family_name
• date_of_birth
• phone_number
• email
• national_id

Address:

• line_1
• locality
• major_admin_division
• postal_code
• country

Minimum required fields

• given_name
• family_name
• address.country

Plus at least one of:

• date_of_birth
• phone_number
• additional address fields

Example request

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/{eval_id}" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "date_of_birth": "1990-05-15",
        "email": "[email protected]",
        "phone_number": "+14155550001",
        "address": {
          "line_1": "123 Main St",
          "locality": "Newark",
          "major_admin_division": "NJ",
          "postal_code": "07102",
          "country": "US"
        }
      }
    }
  }'

{
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+14155550001",
      "address": {
        "line_1": "123 Main St",
        "locality": "Newark",
        "major_admin_division": "NJ",
        "postal_code": "07102",
        "country": "US"
      }
    }
  }
}

Request structure

data
├─ otp (optional)
│  └─ code
└─ individual (optional)
   ├─ given_name
   ├─ family_name
   ├─ email
   └─ address
      ├─ line_1
      ├─ locality
      ├─ major_admin_division
      ├─ postal_code
      └─ country

Only include the object relevant to the current step (otp or individual). For complete field definitions, see the Evaluation API Reference.

Response behavior

After submitting a PATCH request, RiskOS™ will:

• Continue the evaluation.
• Return an updated response.
• Either:
  • Complete the evaluation.
  • Request additional input.
  • Trigger further verification (such as DocV).

Use the response to determine the next step in your flow.

See Handle Results for routing logic and response handling.

Possible outcomes

After submitting a PATCH request, RiskOS™ may return:

Error handling

If the PATCH request returns an HTTP error, handle it before processing any evaluation logic.

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

Implementation flow

1. Create an evaluation (POST).
2. Receive response (REVIEW or final decision).
3. If required:
   • Collect One-Time Passcode or additional data.
4. Submit using PATCH /api/evaluation/{eval_id}.
5. Repeat until final decision is returned.

Summary

• Use PATCH to continue an evaluation after ON_HOLD.
• Submit only the required data for the current step.
• Continue the flow until a final decision is reached.