Custom Fields in Evaluation Requests

How it works

📘

Note:

For the complete evaluation request schema, including all standard fields available alongside custom, see the Evaluation API reference.

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.

Example request

Evaluation-level and individual-level custom data

{
  "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:

$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

"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.