Create or update suggestions
POST/api/v1/suggestions
Feed one event, or a batch of them, into a user's Suggested Entries.
This is the endpoint an integration uses: a calendar sync, a ticketing system, a badge reader — anything that knows a person spent time on something and wants Journyx to offer it as an entry.
POST is an upsert, not a create
Suggestions are keyed on source_id within a source_category. Posting
an event whose source_id has been seen before updates the existing
suggestion rather than adding a second one.
That is what a feeder wants: re-sending yesterday's calendar after a
meeting moved should correct the suggestion, not duplicate it. It also
means you can re-run a sync safely — repeated events come back as
unchanged.
Send no source_id and every POST creates a new suggestion, since
there is nothing to match on.
One event or many
Post a single event as the request body. Post many by naming them in a
suggestions array. A bare JSON array at the top level is rejected.
The two modes answer differently, and it is a real difference:
| Single event | Batch | |
|---|---|---|
| Success | 201 Created with a Location header | 200 OK with item_results |
| Body | Empty — read Location or uri for the new ID | Per-item results and counts |
| A bad event | 400, nothing is stored | That item reports error; the rest are stored |
predict default | true | false |
A single event in the suggestions array counts as a batch. If you want
the batch response shape for one event, that is how to ask for it.
A batch is capped at 500 events by default; an administrator can change
the limit. Exceeding it rejects the whole request with a 400 that names
the maximum.
Reading the batch result
A batch always answers 200, even when some events failed — the ones
that succeeded really were stored, and no single status code describes a
partial success. Check num_errors and the per-item status, not just
the status code.
Note that unchanged is a success. A feed that re-sends the same events
each hour should report almost nothing but unchanged, and treating that
as a failure is a common mistake.
What you may set
The event shape is flat: send id_project, not
properties.id_project. Fields the engine owns — state,
source_category, the audit fields, anything ending in _predict — are
refused with a 400 naming them, rather than dropped silently, so a
client finds out its write did not take. To pin a value the engine would
otherwise guess, drop the _predict suffix.
Every event needs text to read and a start and end date; see the request schema for the exact requirements.
Suggesting for another user
Set id_user. This needs a timekeeping ability over that user, and each
distinct owner in a batch is authorized before anything is written — so a
batch naming a user you cannot act for is refused whole, rather than
partly applied.
Any authenticated user can create suggestions for themselves. Creating
them for another user requires a timekeeping ability over that user. Over
a Bearer token this needs the jx:suggestions:write scope, which the
Suggest my entries connection level grants on its own — a feeder does
not need access to the person's timesheets.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 404
- 500
- 503
A batch was processed. Some events may still have failed — check
num_errors and the per-item status values.
A single event was stored. The response body carries no suggestion
object; take the new ID from the Location header or the uri field.
Follow with a GET on that URL to read the suggestion back with its
predictions.
Response Headers
The URL of the newly created object.
The ID of the newly created object.
The name of the table where the object was created.
A 400 Bad Request is returned when the client request was malformed,
invalid, or otherwise could not be processed as-is. Usually, the cause for
the error is included in the error.message field of the response, and the
client should correct the request and try again.
See also Core Concepts#Error Responses.
Not authenticated - you must be signed in to access this resource. Please check the section of the documentation on authentication.
A 403 Forbidden response means that you are not authorized to perform
this action or access this object, or the object does not exist at all.
The client request may have been valid but the client does not have permission to access the requested resource or perform the requested action.
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
See also Core Concepts#Error Responses.
Not found - the requested resource could not be found or does not exist. This may also include cases where the resource does exist, but the client does not have permission to access that resource.
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
See also Core Concepts#Error Responses.
Internal server error; an unexpected error occurred on the server. This could be due to a temporary condition or might be the result of a bug in the server software. Also, in some cases, an incorrect client input can trigger this error, and can be resolved by correcting the input.
If the error persists, please contact support along along with the following details when possible:
- any error messages received from the server
- the full request and response details (full headers and body)
- a description of the steps that led to the error
- the time range when it occurred.
Service unavailable - the server is currently unable to handle the request, usually due to maintenance activity on the server. Check if the server's web interface is currently available, or try again later.