Skip to main content

List suggestions

GET 
/api/v1/suggestions

Retrieve Suggested Entries — calendar events and other activity gathered for a user, each with the entry codes the Suggestion Engine predicts for it.

New in Journyx 14.1

The Suggestions REST API was introduced in Journyx 14.1 (26H2). Earlier releases offer only the legacy jxAPI interface.

The default view shows active suggestions only​

By default this returns suggestions the user has neither dismissed nor accepted. Accepted ones are already visible as real entries, so returning them would read as duplicates; dismissed ones are left out for symmetry.

The consequence is worth knowing: in a default response, dismissed and actualized are always false. To see more, filter on either one — and as soon as you filter on state, dismissed, or actualized, the default is dropped entirely and your filter alone decides.

$filter=dismissed eq true                        # dismissed only
$filter=actualized eq true                       # accepted only
$filter=actualized eq true or actualized eq false # everything

dismissed and actualized are readable views of the underlying state column rather than columns themselves, so each accepts only eq with a single true or false. state itself can be filtered directly if you prefer (0 active, 1 dismissed, 2 actualized).

Whose suggestions you see​

Your own, unless you pass managed=true and hold a timekeeping ability over other users — see the parameter for the details. This bound is applied to the query itself, so it holds whatever your $filter says.

Filtering and sorting​

Standard filtering and sorting work on the suggestion's own columns: id_user, source_category, source_id, comment, state, record_date, record_date_end, start_timestamp, end_timestamp, series_id, and the audit fields — plus the dismissed and actualized booleans above.

Nothing inside properties can be filtered or sorted on, including every prediction. It is stored as one JSON document rather than as columns. Fetch and filter client-side if you need to narrow by a predicted code.

Results are ordered by record_date descending unless you say otherwise, putting the events a person is most likely looking at first.

Requesting the raw source event​

source_data — the event as your source originally sent it — is returned only when you name it in $keys. It is not in the default set and not in $keys=$extended, because a single meeting body and attendee list can dwarf the rest of the response.

/api/v1/suggestions/23?$keys=source_data
Required abilities

Any authenticated user can read their own suggestions. Reading another user's requires a timekeeping ability over that user, through a role and a shared group. Over a Bearer token this needs the jx:suggestions scope.

Requires the Suggestion Engine

Reading suggestions, and feeding new ones in, require the site to have a Suggestion Engine license and at least one configured source. Without them these calls return 403. That is a site capability rather than a permission problem, but it is reported the same way.

Request​

Responses​

A successful response from a paged collection; see the results array in the response for the list of results for this page. Additional pages may be available and can be fetched using the @nextLink URL.

Note that the examples given may include keys (fields) that may not always be present in the response, depending on the fields requested in the $keys parameter, the user's permissions, and other system settings.