Workflow configuration 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.

These endpoints set up the parts of the Workflow menu that run on their own: automations, SLA policies, recurring tasks, checklist templates and the holidays in business hours. Queues, resolution categories, interventions, escalations and business hours themselves are in the Workflow API.

Every save goes through the same code as the Workflow pages, so the checks are the pages’ own and a saved rule behaves exactly as one made by hand. All endpoints are POST, take and return JSON, and use the response envelope described in the API overview.

Abilities and conventions

  1. Every endpoint needs the owner’s admin role, as the Workflow pages do.
  2. workflow:read lists; workflow:write creates, updates, reorders, deletes and tests. Write implies read.
  3. Automations need the automations plan feature, SLA policies the SLA feature and holidays the escalations feature, as the pages do. Recurring tasks and checklist templates have no plan gate.
  4. Updates merge: an update takes the record’s id and changes only the fields sent; everything left out keeps its value. A list field (conditions, actions, items), when sent, replaces the whole list.
  5. Automation and SLA policy reorders name every record once, in the new order: the order decides which rule or policy applies first, so a partial list is refused (422).
  6. A save the page would refuse is refused with 422: validation_failed naming the field, or refused with the page’s message. An unknown id gives 404.
  7. Each list endpoint takes with_options: true to add the editor’s vocabulary — the fields, operators, actions and the choices for each (queues, staff, teams, watchlists, stock responses and so on) — so a caller can build a valid record without guessing.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/workflow/automationsworkflow:readList automation rules
POST /api/v1/workflow/automations/createworkflow:writeCreate a rule
POST /api/v1/workflow/automations/updateworkflow:writeChange a rule
POST /api/v1/workflow/automations/toggleworkflow:writeTurn a rule on or off
POST /api/v1/workflow/automations/reorderworkflow:writePut the rules in a new order
POST /api/v1/workflow/automations/deleteworkflow:writeDelete a rule
POST /api/v1/workflow/automations/testworkflow:writeDry-run a rule against a ticket
POST /api/v1/workflow/automations/runsworkflow:readA rule’s latest runs
POST /api/v1/workflow/sla-policiesworkflow:readList SLA policies
POST /api/v1/workflow/sla-policies/createworkflow:writeCreate a policy
POST /api/v1/workflow/sla-policies/updateworkflow:writeChange a policy
POST /api/v1/workflow/sla-policies/reorderworkflow:writePut the policies in a new order
POST /api/v1/workflow/sla-policies/deleteworkflow:writeDelete a policy
POST /api/v1/workflow/recurring-tasksworkflow:readList recurring task schedules
POST /api/v1/workflow/recurring-tasks/createworkflow:writeCreate a schedule
POST /api/v1/workflow/recurring-tasks/updateworkflow:writeChange a schedule
POST /api/v1/workflow/recurring-tasks/run-nowworkflow:writeRaise a task from a schedule now
POST /api/v1/workflow/recurring-tasks/deleteworkflow:writeDelete a schedule
POST /api/v1/workflow/checklist-templatesworkflow:readList checklist templates
POST /api/v1/workflow/checklist-templates/createworkflow:writeCreate a template
POST /api/v1/workflow/checklist-templates/updateworkflow:writeChange a template
POST /api/v1/workflow/checklist-templates/reorderworkflow:writePut the templates in a new order
POST /api/v1/workflow/checklist-templates/deleteworkflow:writeDelete a template
POST /api/v1/workflow/holidaysworkflow:readList holidays
POST /api/v1/workflow/holidays/createworkflow:writeAdd a holiday
POST /api/v1/workflow/holidays/deleteworkflow:writeDelete a holiday

Only recurring-tasks/run-now requires an Idempotency-Key header, because it raises a task; see Idempotency.

Automations

Every reply to an automations call carries rules, the full list in running order. A rule is made of:

  1. name, optional description, and is_enabled (default true).
  2. event — what sets it off, such as ticket.created, customer.replied, staff.replied, note.added, status.changed, ticket.closed, queue.changed, assignee.changed, priority.changed, ticket.idle, task.due, sla.warning, sla.breached or csat.received. For ticket.idle, trigger_options gives the minutes, whom the ticket is waiting_on (us, customer or anyone) and whether to count business_hours only. Each ticket.idle rule runs only when the ticket meets its own trigger_options, so one firing after a short wait does not set off another whose time has not come.
  3. conditions — a list of { field, operator, value }, all of which must hold.
  4. actions — a list of { type, ...parameters }, run in order: for example set_priority, assign, set_queue, add_hashtag, add_checklist, add_note, reply or notify. assign takes an assignee that is a member of staff’s exact address, a team key (team:<id>) of a team that exists, or Unassigned; notify takes a to of assignee, inbox_managers, a member of staff’s exact address or a team key. Anything else is refused with 422, on create and update and on a toggle that turns a rule on. A rule saved earlier that names anyone else skips that action when it runs, does its other actions, and says what it skipped in the line it adds to the ticket’s history. set_queue takes the queue_id of an existing queue other than Drafts, which nothing is ever moved into; any other is refused with 422. A rule can match tickets and tasks alike, and set_queue moves both. A task is never on hold, so when a set_status to on-hold runs on a task, the rule skips that step, does its other actions, and the line it adds to the history says the step was skipped. A reply action’s stock_response_id is saved as a number, even when it is sent as a string of digits, and is returned as one.
  5. stop_after — when true, later rules do not run for the same event once this one has matched. A rule that has already run for a message keeps stopping the later rules on any later pass of the same event (a retry, or another ticket.idle rule coming due), even if its own action has since made its conditions false, and so does a rule whose conditions match but which is held back by the limit of ten runs an hour on the ticket.

with_options: true on the list call returns the whole vocabulary: every event, the condition fields each event offers with their operators and choices, and every action type with its parameters.

curl -X POST https://support.sole-provider.example/api/v1/workflow/automations/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Damaged deliveries to Returns",
    "event": "ticket.created",
    "conditions": [ { "field": "subject", "operator": "contains", "value": "damaged" } ],
    "actions": [
      { "type": "set_queue", "queue_id": 4 },
      { "type": "set_priority", "priority": "30" }
    ]
  }'

A new rule runs last. automations/update takes id and any of the fields above; saving also clears the rule’s record of consecutive failures. automations/toggle takes id and is_enabled; automations/reorder takes ids, first to run first; automations/delete takes id, and the rule’s run history goes with it.

Testing. automations/test is a dry run that changes nothing, though it needs workflow:write. It takes ticket_number or ticket_id — a ticket the owner can see — and a saved rule by id, an unsaved one (event, conditions, actions), or a saved one with some parts replaced. It returns matched, each condition’s verdict, and a description of what each action would do. It needs workflow:write: its answer shows the ticket’s subject, and the conditions you write can test the ticket’s content.

Runs. automations/runs takes id and returns the rule’s latest 25 runs, newest first: the ticket, the event, the outcome with a summary, and any error.

SLA policies

Every reply carries policies, in order, each with its counts of open and breached tickets, and the workspace timezone the targets are measured in. A policy is made of:

  1. name, optional description, is_enabled (default true).
  2. conditions — { field, operator, value } on queue, priority, assignee, subject, from or hashtag. A policy with no conditions catches every ticket that no policy above it caught.
  3. first_response_minutes and resolution_minutes — the targets; give at least one. On update, send a target as null to remove it.
  4. business_hours — count business hours only (default true).

A ticket gets the first enabled policy that matches it, so the order matters; sla-policies/reorder takes every policy’s id once. A change applies to each ticket as its SLA is next worked out. Creating the first policy also adds the pair of SLA automations the page adds; the reply says how many in automations_added.

Deleting. sla-policies/delete takes id. While open tickets use the policy, the call is refused with 409 confirmation_required and open_tickets, the number affected; send confirm: true to go ahead. Their SLA is removed and their list rows refresh; closed tickets keep their SLA record, which the SLA report counts.

Recurring tasks

Every reply carries schedules. A schedule raises a task in its queue each time it comes round, and is made of:

  1. subject and optional notes. The notes are each task’s description, its first note; without them, the description says which schedule raised the task.
  2. queue_id — any queue but Drafts.
  3. assigned_to_email — a member of staff’s address, a team key (team:<id>) or Unassigned; and priority (10–40).
  4. checklist_template_id — optional checklist to add to each task; due_days — optional days until each task is due.
  5. skip_if_open — skip a run while the last task is still open (default true).
  6. next_at (the first time, ISO 8601), repeat_every (1–365), repeat_unit (day, week or month), optional repeat_until (YYYY-MM-DD) and timezone. A first time already past moves to the next occurrence.
  7. is_enabled (default true).

Running now. recurring-tasks/run-now takes id and raises one task straight away, outside the schedule, which carries on as before. The task is created as the scheduled ones are, listed and notified like any other task, and the reply gives its ticket_number. It needs an Idempotency-Key, so a retried call never raises a second task.

recurring-tasks/delete takes id; tasks it already raised stay.

Checklist templates

Checklist templates are the reusable lists that staff, automations and recurring tasks add to tickets and tasks (see Ticket planning API). Every reply carries templates, in order, each with its id, name, description and items.

  1. checklist-templates/create takes name (up to 100 characters), optional description (255) and items, a list of 1 to 100 items of up to 500 characters each; blank items are dropped. The reply carries the new id.
  2. checklist-templates/update takes id and any of those fields; items, when sent, replaces the list.
  3. checklist-templates/reorder takes ids in the new order; each must be an existing template.
  4. checklist-templates/delete takes id. A template an automation or recurring task adds is refused (422 refused, naming it) until that rule or schedule stops using it.

Holidays

Holidays are the days business hours stop for, on top of the weekly hours set with workflow/business-hours/update. holidays lists them; holidays/create takes date (YYYY-MM-DD), name and optional recurring (every year on that day); holidays/delete takes id. Each reply lists every holiday.

{ "date": "2026-12-25", "name": "Christmas Day", "recurring": true }