HomeTrust CenterVisualization types & fields

Visualization types & fields

The complete request and response field reference for reports, charts, tables, KPI cards, and dataset widgets.

Report media typeapplication/json

Contract limits5 MB body · 100 widgets · 12 columns

Report request fieldsPOST, PUT, and PATCH

Field	Type	Requirement	Description
`title`	String	Required	Non-empty report title, maximum 255 characters.
`widgets`	Array	Required	Non-empty list containing 1-100 widget objects. Widget IDs must be unique within the report.
`user_id`	Integer	Optional; API key user	Primary active user within the report's parent account. When omitted on create, the API key owner is used; updates retain the existing user.
`external_id`	String	Optional; generated	Stable producer ID, maximum 128 characters. Reusing it on `POST` replaces that organization's existing report.
`description`	String	Optional; empty	Report description, maximum 65,535 bytes.
`status`	String	Optional; draft	One of `draft`, `published`, `scheduled`, `shared`, or `archived`.
`date_range`	String	Optional; empty	Human-readable reporting-period label, maximum 128 characters.
`schedule`	String	Optional; Manual	Human-readable refresh or delivery label, maximum 64 characters.
`layout`	Object	Optional; 12 columns	JSON layout configuration. The portal uses `columns` and `gap`; default is `{"columns":12,"gap":16}`.

Common widget fieldsEvery widget type

Field	Type	Requirement	Description
`id`	String	Required	Unique within the report. Starts with a letter, then letters, numbers, underscores, or hyphens; maximum 64 characters. `key` is an accepted alias.
`type`	String	Optional; chart	One of `chart`, `table`, `kpi`, or `dataset`.
`title`	String	Optional; empty	Display heading, up to 255 characters.
`width`	Integer	Optional; 12	Width in the report's 12-column grid. Allowed range: 1-12.
`height`	Integer	Optional; 320	Rendered height in pixels. Allowed range: 160-1,400.
`note`	String	Optional; empty	Commentary saved separately with the widget and included in API responses and exports; maximum 20,000 bytes.

Chart widget fieldstype: chart

Field	Type	Requirement	Description
`option`	Object	Required	A safe declarative chart configuration object.
`option.series`	Object or array	Required	One series object or a non-empty array. Each item needs a supported `type`.
`option.dataset`	Object or array	Optional	Dataset definitions for charts, including `source` and dimensions.
`option.title`	Object or array	Optional	Chart title configuration.
`option.tooltip`	Object	Optional	Tooltip configuration such as `trigger` and formatting flags.
`option.legend`	Object	Optional	Legend layout and visibility.
`option.grid`	Object or array	Optional	Plot boundaries and multiple-grid layout.
`option.xAxis / yAxis`	Object or array	Optional	Cartesian axes for line, bar, scatter, candlestick, and related series.
`option.radar`	Object	Optional	Radar indicators and shape configuration.
`option.visualMap`	Object or array	Optional	Visual encoding for ranges, heatmaps, maps, and scatter data.

Available chart types

The platform supports the complete set below. Combine compatible series in one chart when a report needs multiple visual encodings.

Line

line

Trends and changes across ordered values or time.

Bar

bar

Comparisons across categories, including stacked and horizontal layouts.

Pie

pie

Part-to-whole comparisons using pie, donut, or rose layouts.

Scatter

scatter

Relationships and distributions across two numeric dimensions.

Effect Scatter

effectScatter

Scatter data with animated emphasis for notable points.

Candlestick

candlestick

Open, close, low, and high values for financial or range data.

Radar

radar

Multivariate comparisons across a shared set of indicators.

Heatmap

heatmap

Magnitude encoded by color across grids, calendars, or coordinates.

Tree

tree

Parent-child hierarchies displayed as expandable branches.

Treemap

treemap

Hierarchical part-to-whole data shown as nested rectangles.

Sunburst

sunburst

Hierarchical levels shown as concentric radial rings.

Map

map

Values and categories displayed across registered geographic regions.

Lines

lines

Routes, flows, or links drawn across geographic or coordinate systems.

Graph

graph

Network relationships between nodes and links.

Boxplot

boxplot

Statistical distributions using quartiles, medians, and outliers.

Parallel

parallel

High-dimensional records compared across parallel axes.

Gauge

gauge

A current value shown against a defined scale or target.

Funnel

funnel

Stage-to-stage volume and conversion comparisons.

Sankey

sankey

Weighted flows between categories or process stages.

Theme River

themeRiver

Category volume changing over time in a flowing stream layout.

Pictorial Bar

pictorialBar

Bar values rendered with repeated or scaled symbols.

Custom Series

custom

Safe custom point, rectangle, or line marks driven by declarative series data.

Custom series use a safe local renderer with shape set to point, rect, or line. The API preserves other safe declarative option fields and rejects prototype-related keys, submitted renderItem callbacks, script URLs, function expressions, arrow functions, and structures deeper than 30 levels.

Table widget fieldstype: table

Field	Type	Requirement	Description
`columns`	Array	Required; non-empty	Each column is a string or an object with `key` and optional `label`.
`columns[].key`	String	Object columns	Property read from object rows.
`columns[].label`	String	Optional	Visible column heading; defaults to `key`.
`rows`	Array	Required; may be empty	Each row may be an object keyed by column key or an array aligned to column order.

KPI widget fieldstype: kpi

Field	Type	Requirement	Description
`value`	String, number, boolean, or null	Required	Primary value rendered in the KPI card.
`label`	String	Optional	Supporting label rendered below the value.
`delta`	Scalar	Optional	Comparison, trend, or change value rendered with the KPI.

Dataset widget fieldstype: dataset

Field	Type	Requirement	Description
`data`	Any JSON value	Optional	Preferred field for inspectable source data. Objects and arrays are formatted as JSON.
`dataset`	Any JSON value	Optional alias	Rendered when `data` is not present.

Chart widgettype: chart

{
    "id": "revenue-trend",
    "type": "chart",
    "title": "Revenue vs target",
    "width": 8,
    "height": 360,
    "option": {
        "tooltip": {
            "trigger": "axis"
        },
        "legend": [],
        "dataset": {
            "source": [
                [
                    "day",
                    "Revenue",
                    "Target"
                ],
                [
                    "Mon",
                    18400,
                    17000
                ],
                [
                    "Tue",
                    21300,
                    18000
                ]
            ]
        },
        "xAxis": {
            "type": "category"
        },
        "yAxis": [],
        "series": [
            {
                "type": "bar"
            },
            {
                "type": "line"
            }
        ]
    },
    "note": "Revenue remained above target."
}

Use a declarative chart option; executable callbacks are not accepted.

Table widgettype: table

{
    "id": "regional-detail",
    "type": "table",
    "title": "Regional performance",
    "columns": [
        {
            "key": "region",
            "label": "Region"
        },
        {
            "key": "revenue",
            "label": "Revenue"
        }
    ],
    "rows": [
        {
            "region": "West",
            "revenue": "$218,400"
        },
        {
            "region": "Central",
            "revenue": "$176,900"
        }
    ]
}

Columns may be strings or keyed label objects; rows may be arrays or objects.

KPI widgettype: kpi

{
    "id": "pipeline-coverage",
    "type": "kpi",
    "title": "Pipeline coverage",
    "width": 4,
    "height": 220,
    "value": "3.8x",
    "label": "Next-quarter target",
    "delta": "+0.4x"
}

The required value can be a string, number, boolean, or null.

Dataset widgettype: dataset

{
    "id": "source-records",
    "type": "dataset",
    "title": "Normalized source records",
    "data": [
        {
            "account_id": "acct_1042",
            "segment": "Enterprise",
            "arr": 218400
        },
        {
            "account_id": "acct_1088",
            "segment": "Mid-market",
            "arr": 176900
        }
    ]
}

Dataset widgets make the underlying structured records directly inspectable.

Report response fieldsReturned data object

Field	Type	Requirement	Description
`id`	String	Always	Server-generated 24-character report ID used in report and widget URLs.
`external_id`	String	Always	Caller-supplied idempotency key, or generated as `report_{id}`.
`title`	String	Always	Report title.
`status`	String	Always	Capitalized status label such as `Published` or `Archived`.
`type`	String	Always	Fixed value: `Data visualization`.
`date_range`	String	Always	Saved label, or `All data` when empty.
`schedule`	String	Always	Saved label, or `Manual` when empty.
`client_id`	Integer	Always	Parent client account that owns and scopes the report. Zero for accounts that are not client-owned.
`user_id`	Integer	Always	Primary active user assigned within the report's parent account.
`user_label`	String	Always	Human-readable label for the primary user.
`owner_user_id`	Integer	Always	Immutable portal user ID that originally created the report.
`updated_at`	Datetime string	Always	Database update timestamp.
`updated_display`	String	Always	Human-readable update date in `M j, Y` format.
`share_enabled`	Boolean	Always	Whether a public share token is active.
`widget_types`	Array of strings	Always	Unique capitalized widget type labels in the report.
`description`	String	Full report only	Stored report description.
`layout`	Object	Full report only	Normalized layout object; defaults to `{"columns":12,"gap":16}`.
`source`	Object	Full report only	Original complete request representation currently stored for the report.
`share_url`	String	Full report only	Active share URL, or an empty string.
`widgets`	Array	Full report only	Normalized widgets in display order with any saved notes.

Normalized widget response fieldswidgets[]

Field	Type	Requirement	Description
`id`	String	Always	Canonical widget ID, including when the request used `key`.
`type`	String	Always	Normalized lowercase widget type.
`title`	String	Always	Normalized title; empty when omitted.
`width`	Integer	Always	Normalized grid width.
`height`	Integer	Always	Normalized pixel height.
`note`	String	Always	Saved note text; empty when none exists.
`note_updated_at`	Datetime string	Always	Timestamp of the latest note update; empty when no note exists.
`Type-specific fields`	JSON	When supplied	Fields such as `option`, `columns`, `rows`, `value`, `label`, `delta`, `data`, and other safe configuration are preserved.

Response envelope fieldsTop-level JSON

Field	Type	Requirement	Description
`status`	String	Always	Machine-readable result such as `ok`, `unauthorized`, `invalid_json`, `not_found`, or `validation_error`.
`message`	String	When available	Human-readable result or error message.
`data`	Object or array	Success responses	Report, report collection, or other operation result.
`errors`	Array of strings	Validation errors	Field-level validation messages returned with HTTP `422`.

See the chart library in action

Explore live, responsive examples of every visualization family supported by the reporting platform.

Open Chart Gallery

Use these fields in an endpoint

Return to the operation reference for complete request, response, cURL, and Python examples.

API operations