Tickets
Lock
Locks the ticket for the calling User, or refreshes the lock when they already hold it, so that every other User's changes to the ticket (updates, replies and notes, conversation edits, delete, merge, forward, summary) answer 423 Locked until it is released.
The lock lasts five minutes from the holder's last edit or refresh and then lets go on its own; when another User already holds the ticket nothing changes and the response describes that holder instead (is_locked with their user_id), so call this and read the answer rather than checking first.
Send manual true when the User locked the ticket on purpose (the padlock): the lock is then marked is_manual, which a refresh never clears, and the ticket view keeps such a lock across sending a reply and leaving the ticket instead of releasing it.
PUT
/api/{tenant:minlength(2)}/v{version:apiVersion}/tickets/{id}/lock
- Authorisation
- Minimum role: USER
Request arguments
Request body example
Response
- Status
- 200 (OK)
- Type
- DTO_ticket_lock
- Wrapper
- DTO_response_wrap
- Other statuses
- 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 429 (TooManyRequests)
Response body example
DTO_ticket_lock_request
| Name | Type | ReadOnly | Description |
|---|
| manual | Boolean | | True when the User clicked the padlock. Marks the lock as manual (see DTO_ticket_lock.is_manual); false or omitted takes or refreshes it without changing an existing manual mark |
DTO_ticket_lock
| Name | Type | ReadOnly | Description |
|---|
| ticket_id | Int32 | | The ticket the lock belongs to |
| is_locked | Boolean | | True while a User holds the ticket. False means the ticket is free and the remaining properties are empty |
| user_id | Int32 | | The User holding the lock, default when the ticket is free |
| user_name | String | | Display name of the User holding the lock, for the "locked by" indicator |
| locked_at | DateTime (nullable) | | When the lock was first taken (UTC). Refreshing the lock keeps this |
| expires_in_seconds | Int32 | | Seconds until the lock expires on its own unless the holder edits the ticket or refreshes it again. 0 when the ticket is free |
| is_manual | Boolean | | True when the holder took the lock on purpose (the padlock), which the ticket view keeps across sending a reply and leaving the ticket; false for the lock the reply box takes on its own, which is released when the reply is sent. Once set it stays set while the lock lives, a plain refresh never clears it |
Generated Sep 29, 2026 15:11
