Custom Fields

The custom object allows you to send additional metadata in an evaluation request that does not exist in the standard RiskOS™ schema.

Custom fields are optional and support any valid JSON structure.

How it works

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

{
  "id": "eval-123",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "[email protected]",
      "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 will specify 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"

Each level must be referenced 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 field selection hasn't been finalized. 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 (e.g., true), don't send a string ("true"). Mismatched types can cause integration errors at runtime.