## 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:

| Scenario | Signals |
| --- | --- |
| OTP required | `decision = REVIEW`, `status = ON_HOLD`, `sub_status = Awaiting Customer OTP` |
| Additional identity data required | `decision = REVIEW`, `status = ON_HOLD`, `sub_status = More information needed` |

> 📘  
> **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.

SandboxProduction

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

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

For full request and response schemas, see the [Evaluation API Reference](https://help.socure.com/riskos/reference/patchevaluation).

## 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

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `data.individual.otp.code` | String | The 6-digit OTP entered by the user. | `123456` |

### Example request

cURLJSON

```curl
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"
        }
      }
    }
  }'
```

```json
{
  "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

## 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

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `data.individual.given_name` | String | First name of the consumer. | `Jane` |
| `data.individual.family_name` | String | Last name of the consumer. | `Smith` |
| `data.individual.date_of_birth` | String (YYYY-MM-DD) | Consumer date of birth in `YYYY-MM-DD` format. | `1990-05-15` |
| `data.individual.phone_number` | String (E.164) | Phone number in **E.164 format**. The API tolerates hyphens and spaces. | `+14155550001` |
| `data.individual.email` | String | Consumer email address. | `jane.smith@email.com` |
| `data.individual.national_id` | String | Government-issued identifier (for example, SSN). | `123456789` |
| `data.individual.di_session_token` | String (UUID) | Digital Intelligence SDK session token (UUID format). | `sess_123` |
| `data.individual.address.line_1` | String | Primary street address. | `123 Main St` |
| `data.individual.address.line_2` | String | Secondary address information (apartment, suite, unit). | `Apt 4B` |
| `data.individual.address.locality` | String | City or locality. | `Newark` |
| `data.individual.address.major_admin_division` | String | State or province (2-letter US state code when applicable). | `NJ` |
| `data.individual.address.postal_code` | String | ZIP or postal code. | `07102` |
| `data.individual.address.country` | String (ISO 3166-1 alpha-2) | Country code in **ISO 3166-1 alpha-2 format**. | `US` |

### Example request

cURLJSON

```curl
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": "jane.smith@example.com",
        "phone_number": "+14155550001",
        "address": {
          "line_1": "123 Main St",
          "locality": "Newark",
          "major_admin_division": "NJ",
          "postal_code": "07102",
          "country": "US"
        }
      }
    }
  }'
```

```json
{
  "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": "jane.smith@example.com",
      "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

## Response behavior

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

Possible outcomes:

| Outcome | What it means |
| --- | --- |
| `ACCEPT` | The evaluation completed successfully |
| `REJECT` | The evaluation failed |
| `REVIEW` | Additional input or verification is still required |

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.

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

For the full error schema and all error codes, see the [Errors Reference](https://help.socure.com/riskos/reference/errors).

## 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`.