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
- Every endpoint needs the owner’s admin role, as the Workflow pages do.
workflow:readlists;workflow:writecreates, updates, reorders, deletes and tests. Write implies read.- 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.
- Updates merge: an
updatetakes the record’sidand changes only the fields sent; everything left out keeps its value. A list field (conditions, actions, items), when sent, replaces the whole list. - 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). - A save the page would refuse is refused with
422:validation_failednaming the field, orrefusedwith the page’s message. An unknownidgives404. - Each list endpoint takes
with_options: trueto 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 & path | Ability | Purpose |
|---|---|---|
| POST /api/v1/workflow/automations | workflow:read | List automation rules |
| POST /api/v1/workflow/automations/create | workflow:write | Create a rule |
| POST /api/v1/workflow/automations/update | workflow:write | Change a rule |
| POST /api/v1/workflow/automations/toggle | workflow:write | Turn a rule on or off |
| POST /api/v1/workflow/automations/reorder | workflow:write | Put the rules in a new order |
| POST /api/v1/workflow/automations/delete | workflow:write | Delete a rule |
| POST /api/v1/workflow/automations/test | workflow:write | Dry-run a rule against a ticket |
| POST /api/v1/workflow/automations/runs | workflow:read | A rule’s latest runs |
| POST /api/v1/workflow/sla-policies | workflow:read | List SLA policies |
| POST /api/v1/workflow/sla-policies/create | workflow:write | Create a policy |
| POST /api/v1/workflow/sla-policies/update | workflow:write | Change a policy |
| POST /api/v1/workflow/sla-policies/reorder | workflow:write | Put the policies in a new order |
| POST /api/v1/workflow/sla-policies/delete | workflow:write | Delete a policy |
| POST /api/v1/workflow/recurring-tasks | workflow:read | List recurring task schedules |
| POST /api/v1/workflow/recurring-tasks/create | workflow:write | Create a schedule |
| POST /api/v1/workflow/recurring-tasks/update | workflow:write | Change a schedule |
| POST /api/v1/workflow/recurring-tasks/run-now | workflow:write | Raise a task from a schedule now |
| POST /api/v1/workflow/recurring-tasks/delete | workflow:write | Delete a schedule |
| POST /api/v1/workflow/checklist-templates | workflow:read | List checklist templates |
| POST /api/v1/workflow/checklist-templates/create | workflow:write | Create a template |
| POST /api/v1/workflow/checklist-templates/update | workflow:write | Change a template |
| POST /api/v1/workflow/checklist-templates/reorder | workflow:write | Put the templates in a new order |
| POST /api/v1/workflow/checklist-templates/delete | workflow:write | Delete a template |
| POST /api/v1/workflow/holidays | workflow:read | List holidays |
| POST /api/v1/workflow/holidays/create | workflow:write | Add a holiday |
| POST /api/v1/workflow/holidays/delete | workflow:write | Delete 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:
name, optionaldescription, andis_enabled(defaulttrue).event— what sets it off, such asticket.created,customer.replied,staff.replied,note.added,status.changed,ticket.closed,queue.changed,assignee.changed,priority.changed,ticket.idle,task.due,sla.warning,sla.breachedorcsat.received. Forticket.idle,trigger_optionsgives theminutes, whom the ticket iswaiting_on(us,customeroranyone) and whether to countbusiness_hoursonly. Eachticket.idlerule runs only when the ticket meets its owntrigger_options, so one firing after a short wait does not set off another whose time has not come.conditions— a list of{ field, operator, value }, all of which must hold.actions— a list of{ type, ...parameters }, run in order: for exampleset_priority,assign,set_queue,add_hashtag,add_checklist,add_note,replyornotify.assigntakes anassigneethat is a member of staff’s exact address, a team key (team:<id>) of a team that exists, orUnassigned;notifytakes atoofassignee,inbox_managers, a member of staff’s exact address or a team key. Anything else is refused with422, on create and update and on atogglethat 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_queuetakes thequeue_idof an existing queue other than Drafts, which nothing is ever moved into; any other is refused with422. A rule can match tickets and tasks alike, andset_queuemoves both. A task is never on hold, so when aset_statustoon-holdruns 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. Areplyaction’sstock_response_idis saved as a number, even when it is sent as a string of digits, and is returned as one.stop_after— whentrue, 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 anotherticket.idlerule 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:
name, optionaldescription,is_enabled(defaulttrue).conditions—{ field, operator, value }onqueue,priority,assignee,subject,fromorhashtag. A policy with no conditions catches every ticket that no policy above it caught.first_response_minutesandresolution_minutes— the targets; give at least one. On update, send a target asnullto remove it.business_hours— count business hours only (defaulttrue).
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:
subjectand optionalnotes. The notes are each task’s description, its first note; without them, the description says which schedule raised the task.queue_id— any queue but Drafts.assigned_to_email— a member of staff’s address, a team key (team:<id>) orUnassigned; andpriority(10–40).checklist_template_id— optional checklist to add to each task;due_days— optional days until each task is due.skip_if_open— skip a run while the last task is still open (defaulttrue).next_at(the first time, ISO 8601),repeat_every(1–365),repeat_unit(day,weekormonth), optionalrepeat_until(YYYY-MM-DD) andtimezone. A first time already past moves to the next occurrence.is_enabled(defaulttrue).
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.
checklist-templates/createtakesname(up to 100 characters), optionaldescription(255) anditems, a list of 1 to 100 items of up to 500 characters each; blank items are dropped. The reply carries the newid.checklist-templates/updatetakesidand any of those fields;items, when sent, replaces the list.checklist-templates/reordertakesidsin the new order; each must be an existing template.checklist-templates/deletetakesid. 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 }