> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Learning Suggestion object

> A proposed learning item — submitted by anyone, decided by a global administrator, and part of the catalogue only once approved

<Info>
  **Quick Summary:** A learning suggestion is a proposed catalogue entry. Anyone who can see the training library may submit one; the submitter or a global administrator may revise it while it is pending; only a global administrator approves or rejects it. On approval the suggestion becomes a [learning item](/api-docs/resources/learning-item) with the **same id**. A rejected or pending suggestion is never a catalogue item.
</Info>

## Attributes

| Field                                                       | Type                                  | Description                                                                                                                                 |
| ----------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                        | string                                | Opaque id — becomes the learning item id on approval                                                                                        |
| `title`                                                     | string                                |                                                                                                                                             |
| `description` / `url`                                       | string \| null                        |                                                                                                                                             |
| `durationHours` / `cost`                                    | number \| null                        |                                                                                                                                             |
| `type` / `provider` / `format` / `audience` / `courseLevel` | `{ id, name }` \| null                | References into the [reference lists](/api-docs/resources/learning-reference-list)                                                          |
| `referenceId`                                               | string \| null                        |                                                                                                                                             |
| `note`                                                      | string \| null                        | The submitter's note to the reviewer                                                                                                        |
| `suggestedSkillIds`                                         | string\[]                             | Skills the item is proposed for; attached on approval                                                                                       |
| `suggestedCareerIds`                                        | string\[]                             | Careers the item is proposed for; attached on approval                                                                                      |
| `status`                                                    | `pending` \| `approved` \| `rejected` |                                                                                                                                             |
| `submittedById` / `submittedAt`                             | string \| null                        |                                                                                                                                             |
| `approvedById` / `approvedAt`                               | string \| null                        | Set on approval                                                                                                                             |
| `rejectedById` / `rejectedAt` / `rejectionReason`           | string \| null                        | Set on rejection                                                                                                                            |
| `modifiedOnApproval`                                        | boolean                               | True when the administrator changed the submission before approving it. The original submission is retained internally and is not published |

```json theme={null}
{
  "id": "530",
  "title": "Advanced Rigging",
  "description": null,
  "url": "https://learn.example.com/rigging",
  "durationHours": 8,
  "cost": 450,
  "type": { "id": "3", "name": "Online course" },
  "provider": null,
  "format": null,
  "audience": null,
  "courseLevel": null,
  "referenceId": null,
  "note": "Needed for the crane team.",
  "suggestedSkillIds": ["77"],
  "suggestedCareerIds": [],
  "status": "pending",
  "submittedById": "1042",
  "submittedAt": "2026-03-01T09:00:00.000Z",
  "approvedById": null,
  "approvedAt": null,
  "rejectedById": null,
  "rejectedAt": null,
  "rejectionReason": null,
  "modifiedOnApproval": false
}
```

## Operations

| Operation                   | Method and path                                  | Requires scope   |
| --------------------------- | ------------------------------------------------ | ---------------- |
| List suggestions            | `GET /api/v1/learning-suggestions`               | `learning:read`  |
| Get a suggestion            | `GET /api/v1/learning-suggestions/{id}`          | `learning:read`  |
| Submit a suggestion         | `POST /api/v1/learning-suggestions`              | `learning:write` |
| Revise a pending suggestion | `PATCH /api/v1/learning-suggestions/{id}`        | `learning:write` |
| Approve                     | `POST /api/v1/learning-suggestions/{id}/approve` | `learning:write` |
| Reject                      | `POST /api/v1/learning-suggestions/{id}/reject`  | `learning:write` |

The list is filterable by `title`, `status` (the public values `pending`, `approved`, `rejected`), `submittedBy` (a person's **email**), `cost` and `createdAt`, and sortable by `title`, `createdAt` and `cost`. A key acting as a manager lists only the suggestions of the manager's reports, as in the app.

**Submit** needs `title`; `typeId`, the other reference ids, `note`, `skillIds` and `careerIds` are optional. The result is `pending`.

**Revise** takes the same fields as submit (without `note`) and applies to pending suggestions only; a decided suggestion is a [409 conflict](/api-docs/errors/conflict).

**Approve** with an empty body approves the submission as-is. Any field present in the body is applied first — the administrator's modification — and `modifiedOnApproval` becomes true. On approval the suggested skills and careers are attached and the item appears in the catalogue under the same id.

**Reject** requires `{ "reason": "…" }`; the reason is recorded and the suggestion stays visible with `status: rejected`.

## Permissions

Any person who can see the training library may **read and submit** suggestions. **Revising** a pending suggestion is allowed to the person who submitted it and to global administrators. **Approving and rejecting are restricted to global administrators**; any other acting person receives [insufficient-permissions](/api-docs/errors/insufficient-permissions) even when the key holds `learning:write` — this includes the submitter.

## Related errors

* [not-found](/api-docs/errors/not-found) — the suggestion is not in your company, or the id names a catalogue item that was never a suggestion
* [validation-error](/api-docs/errors/validation-error) — a missing title or rejection reason, an unknown reference id, an unknown `status` filter value
* [conflict](/api-docs/errors/conflict) — a revision or decision on a suggestion that is no longer pending
* [insufficient-permissions](/api-docs/errors/insufficient-permissions) — the acting person may not decide, or may not revise someone else's submission