---
title: "Suggestion"
url: "https://dev.4hse.com/api/suggestion"
---

# Suggestion

A **Suggestion** is a recommendation that 4HSE produces for the user to review. Each suggestion has a `type`, which determines how it is interpreted and what applying it does, and a `data` payload describing what is being proposed.

A suggestion is linked to the entities it concerns, so the same recommendation can point at a person, an office, or another resource.

Use this API to:

-   List the open suggestions
-   Apply one or more suggestions (`exec`) — this performs the change the suggestion proposes
-   Dismiss a suggestion (`delete`)

Dismissing is per user and does not erase the suggestion: it is moved to the discarded list of the user who dismissed it, and stays visible to the others.

Version

2.0.0

OpenAPI version

3.0.0

## Authentication

[Section titled “ Authentication ”](#authentication)

### OAuth2

[Section titled “OAuth2 ”](#oauth2)

**Security scheme type:** oauth2

**Flow type:** password

**Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

## Operations

[Section titled “Operations”](#operations)

### index

[Section titled “index”](#operation-indexSuggestion-post)

POST

/v2/suggestion/index

-   

Returns a paginated and filterable list of suggestions.  
Use POST to allow complex filters via JSON payload.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/suggestion/#oauth2)**
-   **[AccessToken](/api/suggestion/#accesstoken)**

#### Request Body

[Section titled “Request Body ”](#request-body)

Parameters for searching suggestions

Select media typeapplication/json

object

**filter**

object

**suggestion\_id**

The unique identifier for the suggestion.

string

**type**

The type of the suggestion.

string

<= 50 characters

Allowed values: ACTION\_SUBSCRIPTION CERTIFICATE\_ACTION

**data**

Additional data related to the suggestion, in JSON format.

string format: json

**per-page**

integer

default: 100 \>= 1

**page**

integer

default: 1 \>= 1

**sort**

Field to sort by. Prefix with minus for descending order (e.g. -type).

string

Allowed values: type

##### Example

```
{  "filter": {    "type": "improvement"  },  "per-page": 10,  "page": 1,  "sort": "type"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of suggestions

Select media typeapplication/json

Array<object>

object

**suggestion\_id**

The unique identifier for the suggestion.

string

**type**

The type of the suggestion.

string

<= 50 characters

Allowed values: ACTION\_SUBSCRIPTION CERTIFICATE\_ACTION

**data**

Additional data related to the suggestion, in JSON format.

string format: json

##### Example

```
{  "suggestion_id": "sug-1",  "type": "improvement",  "data": "{\"message\":\"Add a new feature\"}"}
```

#### Headers

[Section titled “Headers ”](#headers)

**X-Pagination-Current-Page**

integer

Current page

**X-Pagination-Page-Count**

integer

Total number of pages

**X-Pagination-Per-Page**

integer

Number of items per page

**X-Pagination-Total-Count**

integer

Total number of items

### view

[Section titled “view”](#operation-viewSuggestion-get)

GET

/v2/suggestion/view/{id}

-   

Retrieve a suggestion by its unique ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/suggestion/#oauth2)**
-   **[AccessToken](/api/suggestion/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

ID of the suggestion to retrieve

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Suggestion found

Select media typeapplication/json

object

**suggestion\_id**

The unique identifier for the suggestion.

string

**type**

The type of the suggestion.

string

<= 50 characters

Allowed values: ACTION\_SUBSCRIPTION CERTIFICATE\_ACTION

**data**

Additional data related to the suggestion, in JSON format.

string format: json

##### Example

```
{  "suggestion_id": "sug-1",  "type": "improvement",  "data": "{\"message\":\"Add a new feature\"}"}
```

##### 404

[Section titled “404 ”](#404)

Suggestion not found

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.