Personal settings 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 of a member of staff’s own settings change what Tickiti does for them: their availability — the out-of-office periods that mark them away, hold their WhatsApp notifications and give customers an out-of-office message — and their email signature from their profile. These endpoints, in the Settings family, read and change them for the token’s owner, and only for them: there is no user parameter.

All endpoints are POST, take and return JSON, and use the response envelope described in the API overview. The token’s owner must be a member of staff. Password, email address, two-factor sign-in and WhatsApp verification are changed on the profile page.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/settings/availabilitysettings:readYour out-of-office periods
POST /api/v1/settings/availability/createsettings:writeAdd a period
POST /api/v1/settings/availability/updatesettings:writeChange a period
POST /api/v1/settings/availability/deletesettings:writeDelete a period
POST /api/v1/settings/signaturesettings:readYour signature
POST /api/v1/settings/signature/updatesettings:writeSet or clear your signature

Write implies read. None of these endpoints takes an Idempotency-Key.

Out of office

Every reply carries periods, the owner’s out-of-office periods, newest first, and the workspace timezone they are set in.

availability/create takes:

  1. all_day — required. When true, give start_date and end_date (YYYY-MM-DD, whole days in the workspace time zone); otherwise starts_at and ends_at (ISO 8601).
  2. staff_message — optional, up to 2,000 characters, shown to colleagues.
  3. customer_message — optional, up to 2,000 characters, the out-of-office message customers are sent.
curl -X POST https://support.sole-provider.example/api/v1/settings/availability/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "all_day": true,
    "start_date": "2026-12-22",
    "end_date": "2026-12-29",
    "staff_message": "Away over the holidays; Sam is covering Returns.",
    "customer_message": "Thanks for your message. I am away until 30 December and a colleague will pick this up."
  }'

availability/update takes id and any of the same fields; what is left out is kept. availability/delete takes id. A period that is not the owner’s gives 404.

A token an Axial agent task works with cannot set what the owner’s customers receive: availability/create and availability/update are refused with 403 when the period would carry a customer_message, including an update to a period that already has one. A period with no customer message goes ahead.

Signature

settings/signature returns the signature as the reply editor has it: the workspace policy, whether personal signatures are allowed (allow_personal), the workspace signature filled in for the owner (system_text), their own personal_text, which one a reply starts with (default_mode), and the placeholders a workspace signature may use (tokens).

signature/update takes signature, up to 1,000 characters; an empty string or null clears it. It is saved whether or not personal signatures are allowed, as on the profile; while they are off, it is used only on a reply that chooses it. A token an Axial agent task works with cannot change it (403), since it goes on the owner’s replies to customers. A reply sent through the API chooses its signature with signature on tickets/respond — see Reply to ticket API.