Bulk ticket update API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

Two endpoints change many tickets in one call. tickets/update-many is the ticket list’s multi-select Save: status, hold date, queue, assignee, priority, resolution and task dates across up to 100 tickets. workflow/queues/move-tickets moves every ticket in one queue to another, as Workflow → Queues does when a queue is emptied.

Both run each ticket through the same ticket engine as the web app. Every changed ticket gets its line in the ticket history, the people who follow it are notified as usual, ticket lists and perspective counts refresh, and anyone with the ticket open sees the change straight away. All endpoints are POST, take and return JSON, and use the response envelope described in the API overview.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/tickets/update-manytickets:writeChange up to 100 tickets, each judged on its own
POST /api/v1/workflow/queues/move-ticketsworkflow:write (admin)Move every ticket in one queue to another

Neither endpoint takes an Idempotency-Key: each sets values, so repeating a call leaves the tickets as they are. Both accept dry_run: true, which reports what the call would do and changes nothing.

Update many tickets

POST /api/v1/tickets/update-many

Body:

  1. ticket_numbers — required; 1 to 100 distinct ticket numbers.
  2. status — open, on-hold or closed. A task is never on hold.
  3. on_hold_until — a date. Required with on-hold; sent on its own it puts the tickets on hold until that date.
  4. queue (a queue name) or queue_id — one or the other. Tickets and tasks move to any queue alike, but nothing moves into Drafts.
  5. assigned_to_email — a member of staff’s address, a team key (team:<id>, see tickets/teams) or Unassigned.
  6. priority — Low, Normal, High or Urgent (or 10–40).
  7. resolved — a resolution category, by id or name (see tickets/resolutions).
  8. start_date and due_date — YYYY-MM-DD, or none to clear the date. These are the dates tasks carry; tickets/show returns them.
  9. dry_run — boolean.

Give at least one change; a call with none is refused with 422 validation_failed. An unknown queue, assignee, priority or resolution is refused the same way, naming the field, and nothing changes.

Who may change what

The call runs as the token’s owner, who must be a member of staff. Each ticket is judged on its own, with the rules the ticket list applies to a person making the same change by hand:

  1. The owner must be able to see the ticket: they are its assignee (in person or as a member of the assigned team), a participant, or have access to its queue. A ticket they cannot see is refused exactly as a number that is no ticket, so the reply does not say whether it exists.
  2. Queue. Moving a ticket needs Manage on both the queue it is in and the queue it goes to — unless the ticket’s assignee after the change manages the destination queue.
  3. Assignee. Reassigning needs Manage on the ticket’s queue (after any queue change in the same call) — unless the new assignee manages it. A team manages a queue when any of its members does; Unassigned manages nothing.
  4. Status, hold date, priority and resolution need Manage on the ticket’s queue. The ticket’s current assignee may also close it, with a resolution.
  5. Start and due dates need Manage on the queue, or the ticket to be assigned to the owner in person.

A ticket is also refused when the new queue is Drafts (#528641 can't be put in Drafts: choose the queue it goes to.), when the change would put a task on hold, a hold date alone included (#528641: A task is open or closed: it is never on hold.), when it is locked by someone else, when the owner has an unsent draft on it, when it is an Alert ticket the change would break, or when closing it on a queue that tracks resolutions gives no resolved. See Queue permissions for how Manage is granted.

Refusals are per ticket: a ticket that may not change is listed with the reason, and the others go ahead.

Response

updated lists each changed ticket with every field that changed, from and to; unchanged lists tickets that already had the values sent; refused lists the tickets left alone, with why, in the order the numbers were sent (a number that is no ticket and a ticket the owner cannot see get the same reason, no such ticket, or not one the token owner can see); and ignored_params names any body field the endpoint does not read. On a dry run, would_update takes the place of updated.

curl -X POST https://support.sole-provider.example/api/v1/tickets/update-many \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket_numbers": ["528641", "871546", "615380"],
    "priority": "High"
  }'
{
  "ok": true,
  "data": {
    "dry_run": false,
    "updated": [
      { "ticket_number": "528641",
        "changes": { "priority": { "from": "Normal", "to": "High" } } }
    ],
    "unchanged": ["871546"],
    "refused": [
      { "ticket_number": "615380", "reason": "#615380: you can't change the priority because you don't manage the Sales queue." }
    ],
    "ignored_params": []
  }
}

The ticket history records each change as made through the API in a bulk update, authored by the token’s owner. Opening a ticket is what marks it read; a bulk update leaves read state as it was.

Move every ticket in a queue

POST /api/v1/workflow/queues/move-tickets

Body: the source queue as from_queue (name) or from_queue_id, the destination as to_queue or to_queue_id (a different queue), and optional limit (1–500, default 500), after_id and dry_run.

This is an administrator’s operation: it needs the admin role and workflow:write, and moves the tickets with the administrator’s authority, whatever their queue rights, as Workflow → Queues does. Each ticket’s history records the move, authored by the administrator. Deleted tickets stay where they are. A ticket the administrator has an unsent draft on is skipped and listed in skipped, so the draft is never disturbed. So is a ticket with no message, or a task with no note, which the ticket engine does not change, and one the engine refuses; skipped tickets stay where they are.

Tickets and tasks move together, whatever the two queues. Drafts is neither a source nor a destination: drafts leave it when they are posted. A request that names it is refused as a whole with 422 validation_failed — for example, under errors.to_queue, Nothing is moved into Drafts.

Tickets move oldest first, up to limit per call. remaining says how many are still in the source queue, and more whether any of them are still to be tried. Repeat the call while more is true, passing the reply’s next_after_id as after_id, so each call carries on after the last ticket the one before took. Do not loop on remaining: skipped tickets stay in the source queue and are counted there, so it may never reach 0.

{
  "ok": true,
  "data": {
    "dry_run": false,
    "from_queue": "Returns",
    "to_queue": "Support",
    "moved": 37,
    "ticket_numbers": ["528641", "871546", "..."],
    "skipped": [],
    "remaining": 0,
    "next_after_id": 41877,
    "more": false
  }
}

On a dry run the reply has would_move in place of moved and no ticket_numbers.

workflow/queues/move, described in the Workflow API, also moves a whole queue, in one step and without a history line on each ticket. Use queues/move-tickets when each ticket’s history should show the move.

Related

  1. List tickets API — find the tickets to change; update-many takes their numbers.
  2. Reply to ticket API — change one ticket while posting a response to it.
  3. Ticket planning API — checklists and reminders.