Update a suggestion

PUT 
/api/v1/suggestions/:id_suggestion

Change an existing suggestion: correct the event, pin an entry code, or dismiss and restore it.

This PUT merges; it does not replace

Journyx PUT normally replaces a resource with the body you send. This endpoint does not. It is the one place in the API where that differs, so it is worth reading before you write a client against it.

Concretely:

• A field your body does not mention keeps its stored value. There is no need to read the suggestion, edit it, and send the whole thing back.
• An entry-code field that already holds a value is not blanked by sending it empty. To change one, send the new value; to clear one, you will need to delete the suggestion and re-create it.
• subtype is re-derived on every write, so a value you send may be replaced by the one the engine computes.

The reason is that a write goes through the same intake path the calendar feeders use, and merging is what a feeder needs — a calendar that omits a field is not asserting it is empty. Rather than give this endpoint a second, divergent write path, it shares the feeders' one and documents the difference.

Every write needs the event's dates

Intake re-reads the dates on each write, so an update carrying event fields must include a start and end pair even though the stored suggestion already has them. Omitting them is a 400.

The exception is a body carrying only dismissed: that changes the disposition without going through intake at all, so it needs nothing else. This is the cheap, common case — a user setting a suggestion aside.

Dismissing and restoring

dismissed is the only disposition a client may set. Send true to set the suggestion aside, false to bring it back.

actualized is read-only — it is set when someone accepts the suggestion into a real entry — and sending it is a 400.

Concurrency

As with all PUT modifications, you must include the If-Match header with the current ETag value of the user record or the request will fail with a "412 Precondition Failed" status code. The ETag value can be obtained by retrieving the item with a GET request and examining the ETag header in the response.

Expect 412 here more often than on other resources. The Suggestion Engine rewrites suggestions in the background — a calendar refresh or an entry-screen load re-predicts them — so an ETag can go stale without anyone touching the API. Treat 412 as routine: re-GET, re-apply your change, and retry. The ETag on the PUT response is already refreshed, so a chain of edits needs no intervening GET.

Required abilities

Your own suggestions, or those of a user you hold a timekeeping ability over. Over a Bearer token this needs the jx:suggestions:write scope.

Request

Responses

204

The suggestion was updated. The response body is empty; the ETag header carries the refreshed value, so you can chain further edits without another GET.

Response Headers

Location

URI of the object

ETag

The current ETag value for this object, which is needed to perform a PUT modification.

See the modifying objects guide and the related tutorial section.

400

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.

401

Not authenticated - you must be signed in to access this resource. Please check the section of the documentation on authentication.

403

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.

403 Forbidden also used when objects don't exist

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.

404

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.

403 Forbidden also used when objects don't exist

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.

412

Precondition Failed — the If-Match ETag is not current, so the suggestion changed since you read it. Fetch it again, re-apply your change, and retry. Common here; see the note on concurrency above.

428

Precondition Required — the If-Match header is missing. It is required on every update, to prevent lost updates.

500

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.

503

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.