The Learning Reference List object

Quick Summary: A learning item points at up to five reference entries: its type, provider, format, audience and course level. Each list is company-defined, ordered, and served under one parameterised path, /api/v1/learning-reference/{list}, with the same shape and operations for all five. Deleting an entry in use is guarded.

Lists

`{list}`	Describes	On the item as
`learning-types`	What kind of content (course, video, document…)	`type` — required on every item
`training-providers`	Who delivers it	`provider`
`training-formats`	How it is delivered (online, classroom…)	`format`
`training-audiences`	Who it is for	`audience`
`training-course-levels`	Difficulty	`courseLevel`

Any other value for {list} is a validation error.

Attributes

Field	Type	Description
`id`	string	Opaque entry id
`name`	string
`description`	string \| null
`position`	integer	1-based position in the list’s display order
`referenceCount`	integer	Learning items (and suggestions) using the entry
`createdAt`	string \| null

{
  "id": "3",
  "name": "Online course",
  "description": "Self-paced, browser based.",
  "position": 1,
  "referenceCount": 14,
  "createdAt": "2026-01-12T08:30:00.000Z"
}

Operations

Operation	Method and path	Requires scope
List entries	`GET /api/v1/learning-reference/{list}`	`learning:read`
List entries in use	`GET /api/v1/learning-reference/{list}/in-use`	`learning:read`
Get an entry	`GET /api/v1/learning-reference/{list}/{id}`	`learning:read`
Create an entry	`POST /api/v1/learning-reference/{list}`	`learning:write`
Update an entry	`PATCH /api/v1/learning-reference/{list}/{id}`	`learning:write`
Reorder a list	`POST /api/v1/learning-reference/{list}/reorder`	`learning:write`
Delete an entry	`DELETE /api/v1/learning-reference/{list}/{id}`	`learning:write`

Lists come back in display order and are filterable by name (eq, neq, like, in) and sortable by name and position. The in-use read returns only entries with a referenceCount above zero — the read that drives filter options. Create takes { "name": "Workshop", "description": "…" } and places the entry at the end of the list. Update takes name and description. Reorder takes { "ids": ["3", "1", "2"] } and must list every entry of the list exactly once, in the desired order; a partial, duplicated or foreign list is 422 unprocessable. The response is the whole list with new positions. Delete is guarded. If any learning item uses the entry the call answers 409 conflict with confirmRequired: true and dependencies: { "learningItems": 14 }. Retry with ?confirm=true: the entry is removed and the reference is cleared from every item — the item’s type, provider, format, audience or courseLevel becomes null.

Permissions

Any person who can see the training library can read the lists. Creating, updating, reordering and deleting entries follows the same rule as authoring learning items: global administrators, managers, full-access users and employees may change them; administrators, directors and executives receive insufficient-permissions. Deleting is restricted to global administrators. Every operation is company-scoped: an entry of another company is a 404 to read, update, reorder or delete.

validation-error — an unknown {list}, a missing name, an unsupported filter operator
not-found — the entry is not in your company
unprocessable — an incomplete reorder list
conflict — the guarded delete

Using the API

System Objects

Team Data

Errors

The Learning Reference List object

Lists

Attributes

Operations

Permissions

​Lists

​Attributes

​Operations

​Permissions

​Related errors

Lists

Attributes

Operations

Permissions

Related errors