Risk Segmentation Configs

Risk segmentation configurations are saved views for the Risk Segmentation dashboard on an analysis. Each config describes how results should be broken down (the segments), which summary columns appear in the table, and optional dashboard filters. Configs correspond to the segment picker in the web application. This API manages those saved configurations only. It does not return dashboard table data or support drilling into entries. (The web app loads table rows through separate private endpoints.) Each config belongs to one analysis. analysisId is the analysis run id (the same id returned by /v1/analyses for the run, not the analysis context id). Names must be unique within an analysis.

Typical workflow

Create a config with analysisId, a unique name, ordered segments, and ordered columns.
Query configs for an analysis (for example { "$eq": ["analysisId", "<analysis-run-id>"] }).
Read a config by id when you need the full definition.
Delete configs you no longer need.

There is no update operation on the public API. To change a config, delete it and create a new one.

Segments

segments is an ordered list. Order defines the hierarchy shown in the dashboard table (outer segments first, inner segments nested beneath them). Each value must be a valid SQL identifier. risk_score is required in segments. Create requests without it are rejected.

Built-in segment keys (general ledger and similar analyses)

Segment	Meaning
`risk_group`	Risk assertion category (for example asset vs profit-and-loss assertion scores).
`risk_score`	Individual risk score (ensemble). Required.
`account_l1` … `account_l5`	Account grouping hierarchy levels. Use only levels that exist for the analysis.
`population_<code>`	Group by a population tag code (prefix is literal `population_`).
`category_<code>`	Group by a population category code (prefix is literal `category_`).

The web application builds population segment ids from enabled populations on the analysis.

Custom analysis segments

For custom (flex) analyses, additional segment fields may be used when they name categorical columns on the analysis entry data table. Those names must be valid SQL identifiers and must exist on the table. The analysis designer uses the same rules when defining risk segmentation there.

Columns

columns is an ordered list of metric fields displayed in the dashboard table for each segment row. Values must match the snake_case ids below (these are the same ids the web application sends as columns).

Count and value summaries

Column	Meaning
`total_count`	Entry count in the segment.
`total_value`	Total monetary value.
`total_value_dr`	Total debit value.
`total_value_cr`	Total credit value.
`net_activity`	Net activity value.
`risk_avg`	Average risk score in the segment.

High / medium / low counts and values

Column	Meaning
`high_count`, `medium_count`, `low_count`	Entry counts at each risk level.
`high_value`, `medium_value`, `low_value`	Monetary totals at each risk level.
`high_value_dr`, `high_value_cr`, …	Debit/credit splits of H/M/L value columns (same pattern as above).

High / medium / low percentages

Column	Meaning
`percent_high_risk`, `percent_med_risk`, `percent_low_risk`	Percent of entries at each risk level.
`percent_high_risk_dr`, `percent_high_risk_cr`, …	Debit/credit splits of the percentage columns (same pattern).

Debit/credit column variants apply to general ledger analyses that expose separate debit and credit totals. Omit them when not relevant to the analysis type. Do not put segment keys (such as risk_group or account_l1) in columns; those belong in segments.

Optional filters

These fields mirror the Risk group and Risk score filters on the dashboard facet bar. They restrict which scores and categories are in scope when the config is opened. They do not add extra grouping levels.

Field	Meaning
`riskScoreIds`	Risk score ids (ensemble object ids) to include. When omitted or empty, all enabled risk scores for the analysis are in scope. When `risk_score` is not a segment, this still limits which scores contribute to aggregated columns.
`riskGroups`	Risk group category names to include (for example `GENERAL`, `ASSETS`, `PROFIT_LOSS`, or a custom risk score category name). When omitted or empty, all groups are in scope.

riskGroups values are category labels, not risk range ids and not entries from /v1/risk-ranges.

Other fields

Field	Meaning
`displayCellVisuals`	When `true`, the dashboard shows in-cell sparkline visuals for numeric columns. Defaults to `false`. Maps to internal `displayTableSparklines`.
`enabled`	Whether the config is active. Defaults to `true`. Disabled configs remain stored but are not selected by default in the web application.
`analysisTypeId`	Set automatically on create from the analysis. Returned on read and query; do not send on create.

Example create request

{
  "analysisId": "123456789012345678901234",
  "name": "Risk group and score",
  "segments": ["risk_group", "risk_score"],
  "columns": ["total_count", "total_value", "risk_avg"],
  "displayCellVisuals": false,
  "enabled": true,
  "riskScoreIds": ["abcdefabcdefabcdefabcd"],
  "riskGroups": ["GENERAL", "PROFIT_LOSS"]
}

Validation

analysisId must reference an existing analysis run.
name must be unique among configs for that analysis.
segments must include risk_score.
Segment and column names must be valid SQL identifiers.
Invalid segment or column combinations for the analysis type may be rejected at create time.

Query

See the query operation description for filterable fields.

Overview

Details

Webhooks

API reference

Typical workflow

Segments

Built-in segment keys (general ledger and similar analyses)

Custom analysis segments

Columns

Count and value summaries

High / medium / low counts and values

High / medium / low percentages

Optional filters

Other fields

Example create request

Validation

Query

​Typical workflow

​Segments

​Built-in segment keys (general ledger and similar analyses)

​Custom analysis segments

​Columns

​Count and value summaries

​High / medium / low counts and values

​High / medium / low percentages

​Optional filters

​Other fields

​Example create request

​Validation

​Query

Typical workflow

Segments

Built-in segment keys (general ledger and similar analyses)

Custom analysis segments

Columns

Count and value summaries

High / medium / low counts and values

High / medium / low percentages

Optional filters

Other fields

Example create request

Validation

Query