Risk — Field reference

Object shapes for the Risk API. Every field is optional in the response — only those requested (via ?fields=) or in the default set are returned. ?fields=all returns the full set.

Risk register

Field	Type	Description
key	string	Register key, e.g. RR-PROG
title	string	Register name
id	string	Unique identifier
createdBy	string	Creator's email
status	object	{ status: <label>, id: <statusId> }

Risk

Field	Type	Description
key	string	Human-readable Risk Key — <registerKey>-<riskNumber>, e.g. RR-PROG-7. Falls back to R-<n> when the register has no key.
title	string	Risk title
id	string	Unique identifier
riskDesc	string	Long-form description as plain text with preserved line breaks. Rich-text from the in-app editor is converted to text. Also accepted as description for legacy callers.
mitigationActions	string	Mitigation actions as plain text with preserved line breaks
createdBy	string	Creator's email
impact	string	Impact level title — e.g. Low, Medium, High
probability	string	Probability level title — e.g. Low, Medium, High, Likely, Rare
riskLevel	object	Computed risk band { title, color }. Derived from impact × probability against the register's risk matrix. See Risk Level.
raisedDate	string	Date raised — dd-MMM-yyyy
resolutionDate	string	Target resolution date — dd-MMM-yyyy
linkedItems	array	[{ key, id }, …] — linked board items
boardTeams	array	[{ teamTitle, teamId }, …]
boardSprints	array	[{ sprintTitle, sprintId }, …]
status	object	{ status: <label>, id: <statusId> }
riskRegister	object	{ riskRegister: <name>, id: <registerId> }
responsible	object	{ user: <fullName>, id: <userId> } — omitted when no Responsible user is assigned
watcherList	array	[{ Watcher: <fullName>, id: <userId> }, …]
customFields	array	Type-aware projection of all user-defined custom fields. See Custom fields.
conversation	array	Comment thread (only when requested via ?fields=conversation)

Custom fields

Each user-defined field on the register's layout is projected into the customFields array of the risk.

"customFields": [
  { "id": "<field-id>", "title": "Business Unit",  "type": "singleselect", "value": "Finance" },
  { "id": "<field-id>", "title": "Backup Owner",   "type": "userpicker",   "value": { "id": "<user-id>", "fullName": "Jane Doe" } },
  { "id": "<field-id>", "title": "External Wiki",  "type": "link",         "value": { "name": "Spec doc", "url": "https://wiki.acme.com/spec" } },
  { "id": "<field-id>", "title": "Affected Areas", "type": "multiselect",  "value": ["Frontend", "API"] },
  { "id": "<field-id>", "title": "Reviewed On",    "type": "date",         "value": "2026-05-21" }
]

Entry shape

Key	Description
id	The custom field definition ID
title	The field's display label (configured in Layout)
type	Field type — see the table below
value	The risk's value for that field, projected by type

Value projection by type

type	Returned value	Notes
userpicker	{ id, fullName }	Only ID and display name are returned
singleselect / dropdown / status	string — the option's title	e.g. "Finance", "In Progress"
multiselect	[ <title>, <title>, … ]	Array of option titles; empty array if none selected
link	{ name, url }	url is checked for a safe scheme — only http://, https://, and mailto: are returned. Other schemes are dropped; name is still returned so the link renders as plain text.
date	ISO-8601 date or millisecond timestamp	—
text / number	string / number	Returned as-is

customFields is included in ?fields=all (and the default response when no fields= is sent). It can also be requested explicitly with ?fields=customFields, or omitted by listing only the other fields you need.

Risk Level — how it is computed

riskLevel is computed at response time from the risk's impact × probability against the risk register's risk matrix. The result mirrors what the Kendis UI shows on the risk card.

Algorithm

1. Score = impact value × probability value.
2. Match the highest band in the register's risk matrix whose lower limit ≤ score.
3. Return { title, color } of the matching band, or omit the field when any input is missing.

Worked examples

Register configuration	Impact	Probability	Score	Matching band	Returned riskLevel
3-band: High (≥9) · Medium (≥4) · Low (≥0)	Medium (2)	High (3)	6	Medium (≥4)	{ "title": "Medium", "color": "#f39c12" }
3-band: High (≥9) · Medium (≥4) · Low (≥0)	High (3)	Low (1)	3	Low (≥0)	{ "title": "Low", "color": "#09c199" }
4-band: Severe (≥16) · High (≥12) · Medium (≥8) · Low (≥0)	High (4)	High (4)	16	Severe (≥16)	{ "title": "Severe", "color": "#c0392b" }

The number of bands and their thresholds are per-register (configured in Risk Matrix on the register). The API surface is identical regardless of band count.

Note

If impact or probability is unset on a risk, riskLevel is omitted from the response.

Field selection (?fields=)

Behaviour	Example	Result
No fields= parameter	/api/v1/RR-PROG/risk	Full payload (equivalent to ?fields=all)
?fields=all	/api/v1/RR-PROG/risk?fields=all	All defined fields, including customFields and riskLevel
Comma-separated selection	?fields=key,title,riskLevel,customFields	Only the listed fields
Single field	?fields=customFields	Only that field (plus pagination metadata for list endpoints)

Use selection to reduce payload size on bulk exports (PowerBI / Excel / BI pulls). It does not change pagination or the underlying query — only the projection.