Resume KYC + Fraud + Watchlist Request via API

When to use this endpoint

This endpoint is used to:

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

Common signals:

📘

Important:

Treat each PATCH response as a new decision point. After every update, re-evaluate decision, status, sub_status, and tags to determine the next step.

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 POST /api/evaluation request.
• Submit only the data required for the current step.
• Do not resend previously submitted fields unless they need to be updated.
• Use the updated response to determine whether the evaluation is complete or still requires input.

Submit a One-Time Passcode

Use PATCH to submit the code after the evaluation returns:

• decision = REVIEW
• status = ON_HOLD
• sub_status = Awaiting Customer OTP

What your application should do

1. Prompt the user to enter the 6-digit OTP.
2. Submit the code using PATCH /api/evaluation/{eval_id}.
3. Inspect the updated response to determine the next step.

One-Time Passcode field

Example request

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/5d62575f-e702-4b66-bb35-802450402599" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "f0b3075b-0ae1-4130-9171-88d6c75a982c",
    "timestamp": "2026-03-11T13:23:33.000Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "otp": {
          "code": "123456"
        }
      }
    }
  }'

{
  "id": "f0b3075b-0ae1-4130-9171-88d6c75a982c",
  "timestamp": "2026-03-11T13:23:33.000Z",
  "workflow": "non_hosted_advanced_pre_fill",
  "data": {
    "individual": {
      "otp": {
        "code": "123456"
      }
    }
  }
}

What happens next

After OTP submission, RiskOS™ may:

• keep the evaluation in REVIEW if more input is still required
• return ACCEPT if the evaluation completes successfully
• return REJECT if the evaluation fails

See Handle Results for routing logic and response handling.

Submit identity data

Use PATCH to continue the evaluation when the workflow requires additional identity data.

This commonly occurs after:

• OTP approval is complete
• Prefill data is returned, but more fields are still required
• Prefill is unsuccessful and the user must complete the identity form manually

Detect this state

Look for:

• decision = REVIEW
• status = ON_HOLD
• sub_status = More information needed

Prefill handling

If Prefill data is available:

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

If Prefill data is not available:

• Display a blank or partially completed form
• Collect the required identity fields manually

👍

Tip:

Collect the most complete identity profile possible to improve match accuracy and reduce additional friction.

Field restrictions

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

• date_of_birth
• phone_number
• address.country

Required fields

At minimum, submit:

• given_name
• family_name
• address.country

Plus at least one of:

• date_of_birth
• phone_number
• additional address fields

Minimum rule: Provide given_name, family_name, and address.country, plus at least one of date_of_birth, phone_number, or additional address fields.

Recommended fields

For highest match accuracy, provide:

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

Address:

• line_1
• locality
• major_admin_division
• postal_code
• country

Common field definitions

Example request

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/5d62575f-e702-4b66-bb35-802450402599" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "f0b3075b-0ae1-4130-9171-88d6c75a982c",
    "timestamp": "2026-03-11T13:24:43.000Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "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"
        }
      }
    }
  }'

{
  "id": "f0b3075b-0ae1-4130-9171-88d6c75a982c",
  "timestamp": "2026-03-11T13:24:43.000Z",
  "workflow": "non_hosted_advanced_pre_fill",
  "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"
      }
    }
  }
}

What happens next

After identity data submission, RiskOS™ may:

• return ACCEPT
• return REJECT
• continue in REVIEW if additional verification is still required

See Handle Results for routing logic and Handle Additional Verification for step-up implementation details.

Response behavior

After a PATCH request, RiskOS™ continues the paused workflow and returns an updated evaluation response.

Possible outcomes:

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

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.

Persist evaluation state

Store these fields so your application can resume and route the evaluation correctly:

• id
• eval_id
• decision
• status
• sub_status
• tags
• workflow (optional)

Integration pattern

1. Create the evaluation with POST /api/evaluation.
2. Inspect the response.
3. If the evaluation returns REVIEW, collect the required input.
4. Submit the update with PATCH /api/evaluation/{eval_id}.
5. Re-evaluate the updated response.
6. Continue until the workflow returns a terminal decision.

Key takeaways

• Use PATCH only after the workflow pauses and requires additional input.
• Always reuse the same eval_id.
• Submit only the fields required for the current step.
• Treat each PATCH response as a new decision point.
• Continue the flow until RiskOS™ returns ACCEPT or REJECT.