## How it works

> 📘
>
> **Note**:
>
> For the complete evaluation request schema, including all standard fields available alongside `custom`, see the [Evaluation API reference](https://help.socure.com/riskos/reference/postevaluation).

Custom fields are optional and support any valid JSON structure.

The `custom` object:

- Is optional
- Accepts any valid JSON key-value pairs: strings, numbers, booleans, arrays, and nested objects
- Is available in workflow rules and configured integrations
- Is stored with the evaluation record

Use the `custom` object only when the data does not belong in an existing schema field.

### Supported locations

The `custom` object can be included at multiple levels in the request payload.

| Location                               | Scope                                     |
| -------------------------------------- | ----------------------------------------- |
| `data.custom`                         | Entire evaluation                         |
| `data.individual.custom`              | Primary individual                        |
| `data.individual.address.custom`      | Individual address                        |
| `data.individual.account.custom`      | Individual bank account                   |
| `data.business.custom`                | Business object (`sc_business_onb` only) |

### Example request

Evaluation-level and individual-level custom data

```json
{
  "id": "eval-123",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jane@example.com",
      "custom": {
        "loyalty_tier": "gold",
        "years_as_customer": 3
      }
    },
    "custom": {
      "customer_user_id": "cust-456",
      "origination_channel": "mobile_app",
      "account_creation_date": "2024-01-15"
    }
  }
}
```

## How `custom` fields are used

### 1. Integration inputs

Certain workflow enrichments read specific keys from the `custom` object and pass them to downstream services.

Examples include:

- Sigma transaction signals
- Segmentation inputs
- Configured third-party integrations

Your account team specifies which keys are required for your configured enrichments.

### 2. Workflow rules and conditions

All `custom` fields are exposed as variables in your workflow logic.

Use the full JSON path when referencing values:

```undefined
$data.custom.origination_channel == "mobile_app"
$data.custom.order_amount > 1000
$data.individual.custom.loyalty_tier == "gold"
```

Reference each level explicitly.

### 3. Internal metadata storage

Fields that are not consumed by integrations are still:

- Stored with the evaluation
- Available in workflow rules
- Visible in case tiles
- Included in reporting exports

#### Example request: Sigma transaction data

```json
"custom": {
  "unique_id_user": "user-456",
  "unique_id_transaction": "txn-789",
  "order_amount": 500.00,
  "order_channel": "online",
  "direction": "debit",
  "amount": 500.00,
  "merchant": "Example Store",
  "mcc": "5411"
}
```

> Send only the fields your configured enrichment expects and your workflow uses.

## Best practices

- **Keep it lean.** We recommend **no more than 20-25 custom fields** per request. Only send the fields you actually need for decisioning or case review. Large numbers of custom fields bloat the payload, complicate rule writing, and increase storage costs.

- **Avoid "send everything just in case."** A large custom block is often a sign that you haven't finalized field selection. Work with your Solution Consultant team to identify the specific fields required for your workflow logic before going live.

- **Use standard schema fields when they exist.** Data like individual PII, addresses, accounts, device info, DocV config, and Watchlist filters all have dedicated fields in the request schema. Only use `custom` for data that does not fit into the standard fields.

- **Custom fields are stored, not indexed.** You cannot search or filter cases by custom field values in the RiskOS™ Dashboard. If you need a field to be searchable, discuss with your Solution Consultant team whether it belongs in the standard schema.

- **Set custom fields at creation time.** Provide all custom data in the initial evaluation request. Appending custom data on resume is not reliably supported.

- **Be consistent with types.** If an integration expects a boolean (for example, `true`), don't send a string (`"true"`). Mismatched types can cause integration errors at runtime.