REST API Reference

SautiDesk API

Work with the same tickets, contacts, calls and team your agents use in SautiDesk: open and reply to tickets, assign and resolve them, manage contacts and tasks, and pull the supervisor reports. Every request is made with an API key issued by a workspace owner or admin, and acts as the person the key was issued for.

Base URL

https://api.sautidesk.com

Version

v1 (/v1/desk/*)

Authentication

Authorization: Bearer <key>

Connect with MCP

The SautiDesk MCP server exposes the SautiDesk API as tools an AI client can call: tickets, contacts, calls, tasks, reports and webhooks. It runs on the same server as the SautiKit one, so Claude Code, Cursor and other MCP clients see the SautiDesk tools with the desk_ prefix.

Server URL

https://mcp.sautidesk.com/mcp

Transport

Streamable HTTP

Authentication

Authorization: Bearer <key>

Use the URL exactly, with /mcp and no trailing slash. Authenticate with a personal SautiDesk API key. The sign-in connector for claude.ai does not grant SautiDesk scopes, so connect with a key. The server lists only the tools your key's scopes allow, and the API checks the key again on every call. The SautiKit address, https://mcp.sautikit.com/mcp, reaches the same server and keeps working, so a client already set up with it needs no change.

$ export SAUTIDESK_KEY=<your API key>

claude mcp add --transport http sautidesk https://mcp.sautidesk.com/mcp \
  --header "Authorization: Bearer $SAUTIDESK_KEY"

Windsurf uses serverUrl in place of url. The cURL check should answer with the server name and its capabilities; a 401 means the key is missing, revoked or malformed.

Get a key and pick scopes

A workspace owner or admin issues the key in SautiDesk under Settings → API keys. The secret is shown once. Each tool needs the scope in this table; a key sees the tools its scopes cover and nothing else.

Scope	Tools
desk.read	Read tools: config, tickets and their timelines, contacts, agents, tasks, templates, queues, categories, numbers and outcomes.
desk.write	Write tools: create and update tickets, contacts and tasks, send messages, place, transfer and wrap calls. Includes desk.read.
desk.supervise	Supervise tools: reports, the admin dashboard, nudges and contact merges. Includes desk.read. Pro workspaces only.
desk.admin	Admin tools: webhooks, API keys, queues, number purchase and workspaces. Includes desk.supervise, desk.write and desk.read.

The key acts as its person. Every call a tool makes runs as that person, is capped by their live role and licences, and is logged against the person and the key id.

Tools (57)

Tool	Scope	What it does
desk_get_config	desk.read	Fetches the SautiDesk workspace configuration, enabled channels, SLA defaults, and feature flags.
desk_list_tickets	desk.read	Lists SautiDesk tickets with optional filtering by status, priority, channel, assignee, queue, contact, or search query.
desk_get_ticket	desk.read	Fetches a single SautiDesk ticket by its UUID.
desk_create_ticket	desk.write	Opens a SautiDesk ticket for a contact (contact_id) or a number/email (to). Nothing is sent: to message someone use desk_send_message and the ticket follows. If they already have an open ticket, that one is returned.
desk_update_ticket	desk.write	Updates a SautiDesk ticket's status, priority, assignee, queue, category, outcome, or subject.
desk_get_ticket_timeline	desk.read	Fetches the unified conversation timeline (messages, call logs, activities, and internal comments) for a SautiDesk ticket.
desk_send_message	desk.write	Sends a message (SMS, WhatsApp or email) to a person. Say who: contact_id, or to for a number or address. The message lands on their open ticket, or opens one; the reply says which (ticket.ref, ticket.opened). There is no send on a ticket.
desk_add_ticket_comment	desk.write	Adds an internal agent note/comment to a SautiDesk ticket.
desk_list_contacts	desk.read	Lists or searches SautiDesk contacts.
desk_lookup_contact	desk.read	Fast lookup of a SautiDesk contact by phone number or email address.
desk_create_contact	desk.write	Creates a new SautiDesk customer contact.
desk_update_contact	desk.write	Updates an existing SautiDesk customer contact.
desk_merge_contacts	desk.supervise	Merges a duplicate SautiDesk contact into a primary contact (requires desk.supervise).
desk_list_agents	desk.read	Lists all SautiDesk agents in the workspace and their live availability states. Pages 100 at a time: pass next_cursor back as cursor.
desk_set_availability	desk.write	Sets the acting SautiDesk agent's availability state (available, busy, away, break, offline).
desk_transfer_call	desk.write	Initiates a blind or attended transfer for an active SautiDesk call.
desk_list_tasks	desk.read	Lists SautiDesk follow-up tasks.
desk_create_task	desk.write	Creates a SautiDesk follow-up task.
desk_update_task	desk.write	Updates or completes a SautiDesk task.
desk_send_dm	desk.write	Sends an internal direct message (DM) in a SautiDesk agent thread.
desk_send_nudge	desk.supervise	Sends a supervisor coaching nudge to a SautiDesk agent (requires desk.supervise).
desk_get_report	desk.supervise	Fetches one SautiDesk supervisor report by name (availability, calls, contacts, cost, day, forecast, hourly, league, missed, numbers, occupancy, owed, reasons, recorded, repeat, replies, scorecard, service, spend, staffing, tickets, transfers, webchat, week, and the channel reports calls-summary, whatsapp, sms, email). The calls, missed and tickets reports also list their rows, 100 a page in `data`: pass next_cursor back as cursor (limit and cursor are ignored by the other reports). Needs the Supervisor licence and SautiDesk Pro.
desk_get_admin_dashboard	desk.supervise	Fetches the live SautiDesk supervisor/admin wallboard snapshot.
desk_send_sms	desk.write	Sends an outbound SMS from SautiDesk.
desk_create_queue	desk.admin	Creates a new SautiDesk queue (requires desk.admin).
desk_list_templates	desk.read	Lists SautiDesk WhatsApp/SMS/email message templates. Pages 100 at a time: pass next_cursor back as cursor.
desk_create_workspace	desk.admin	Creates another SautiDesk workspace owned by the caller (owner only). It gets its own wallet and its own admin key. Confirm with the user first.
desk_search_numbers	desk.admin	Lists phone numbers the workspace can buy, priced in its wallet currency. Numbers another workspace is holding are not listed. Pages: pass next_cursor back as cursor.
desk_hold_number	desk.admin	Holds an available number for 30 minutes so nobody else (including a free trial) can take it while the buyer decides. At most 3 holds per workspace. A repeat returns the existing hold.
desk_release_number_hold	desk.admin	Gives back a hold the workspace has on a number so others can buy it.
desk_claim_number	desk.admin	Buys a number from the workspace wallet balance (the first month is charged now). Spends money: always confirm the number and price with the user first. Top-ups are not possible through a key.
desk_list_webhook_events	desk.admin	The catalogue of event types a SautiDesk webhook can subscribe to, by category.
desk_list_webhooks	desk.admin	Lists the workspace's webhook endpoints (at most ten) with their last delivery.
desk_create_webhook	desk.admin	Creates a webhook endpoint for the given events. The signing secret is in this reply only.
desk_update_webhook	desk.admin	Changes a webhook's URL, description, events or enabled switch. Only the fields given change.
desk_delete_webhook	desk.admin	Deletes a webhook endpoint and stops its deliveries.
desk_test_webhook	desk.admin	Queues a webhook.test delivery to the endpoint so the owner can check it receives and verifies it.
desk_rotate_webhook_secret	desk.admin	Replaces a webhook's signing secret. The old one stops working at once; the new one is in this reply only.
desk_list_webhook_deliveries	desk.admin	A webhook's delivery history, newest first, with an optional status filter. Pages: pass next_cursor back as cursor.
desk_retry_webhook_delivery	desk.admin	Sends one failed webhook delivery again.
desk_list_api_key_people	desk.admin	The people the caller may issue an API key for (a key acts as one person), in `data`; `you` is who the caller acts as. Pages 100 at a time: pass next_cursor back as cursor.
desk_create_api_key	desk.admin	Issues an API key that acts as the named person, with the given scopes (never more than the caller holds). The secret is in this reply only. Keys have no expiry; revoke one to end it. Confirm with the user first.
desk_list_api_keys	desk.admin	Lists every live API key in the workspace (never the secret), newest first, optionally for one person. Pages 100 at a time: pass next_cursor back as cursor.
desk_list_keys_issued_by	desk.admin	The keys that one API key issued. A leaked admin key can make more keys; check here before revoking with cascade. Pages 100 at a time: pass next_cursor back as cursor.
desk_revoke_api_key	desk.admin	Revokes an API key at once; with cascade it also revokes every key that key issued.
desk_place_call	desk.write	Places an outbound call as the acting person: rings their device first, then the number. The call is billed to the workspace wallet: confirm with the user first.
desk_wrap_call	desk.write	Files a wrap-up for a finished call: notes, an outcome (which may open a follow-up task), a category. An outcome that escalates also takes escalate_user_id or escalate_queue_id: the ticket stays open and goes to that teammate or queue. Answers the ticket as it now stands.
desk_get_whatsapp_window	desk.read	Whether a contact's 24-hour WhatsApp customer-service window is open. Outside it only an approved template can be sent.
desk_send_whatsapp_typing	desk.write	Shows the contact a typing indicator while a reply is composed. Always answers {sent, reason}; a missed indicator is cosmetic.
desk_list_queues	desk.read	The workspace's call and ticket queues with their members, in the order set in Settings. Pages: pass next_cursor back as cursor.
desk_list_categories	desk.read	The workspace's ticket categories, in the order set in Settings. Pages: pass next_cursor back as cursor.
desk_get_phone_menu	desk.read	The workspace's one phone menu: its settings in `menu` (null when there is none) and its keys, by digit, as the paged data. Pages: pass next_cursor back as cursor.
desk_list_numbers	desk.read	The phone numbers the workspace owns and what SautiDesk does with each (queue or menu, whether SautiDesk answers it). To find numbers to buy use desk_search_numbers. Pages: pass next_cursor back as cursor.
desk_list_outcomes	desk.read	The workspace's call outcomes (kind=call, default) or ticket outcomes (kind=ticket), the ones Resolve offers. Each says what it does in `effect`. Pages 100 at a time: pass next_cursor back as cursor.
desk_get_activity	desk.read	One item from a ticket timeline (a message, call or note) with its ticket_id.
desk_set_activity_outcome	desk.write	Sets the outcome on a call wrap-up activity (or undoes it).
desk_list_activity_comments	desk.read	The internal comment thread on one timeline activity. Pages: pass next_cursor back as cursor.

Authentication & Scopes

Authenticate every request with a SautiDesk API key. A workspace owner or admin issues it in the SautiDesk console under Settings → API keys and sends it as Authorization: Bearer <key>. The key acts only as that person. When you create it you choose which scopes it carries; that choice is a ceiling, and at each request the key is capped by the person's live role and licences.

Scope	Implied Access
desk.read	Read: tickets, contacts, the team, tasks, notifications, direct messages, templates and the live event stream.
desk.write	Work: open and reply to tickets, resolve, assign, wrap up, manage contacts and tasks, send SMS and direct messages, handle calls.
desk.supervise	Supervise (SautiDesk Pro): the supervisor and executive reports and their exports, report subscriptions, the service-level target and supervisor nudges.
desk.admin	Administer: queues, categories, outcomes, the phone menu, numbers and routing, holidays, channels and templates, members, invitations and licences.

A key is a person

A SautiDesk key acts as one person and as nobody else, so there is no header or query parameter for acting as someone different. Replies, notes and call records carry that person's name. To act as several people, an owner or admin issues a key for each.

The scopes you pick are a ceiling. At every request the key is capped by the person's live role and licences, so a key can never do more than its owner can do today.
Supervise routes (reports, the live floor view, listen-in and exports) work on SautiDesk Pro workspaces only. On Basic they answer 403 desk.pro_required.
A deactivated person's keys, and the keys of anyone un-ticked for Desk, stop working at once.
Each person can hold one live call at a time. Starting a second answers 409 desk.agent_busy.

Sign your agents in

Only workspace owners and admins issue API keys. In SautiDesk it is Settings → API keys; from code it is Issue an API key. Pick the person the key acts as, give it a label and the scopes it may hold.

Admins can issue for members and supervisors. Only the owner can issue for an admin. Nobody can issue for the owner.
The key acts as that person and nobody else, and at every request it is capped by their live role and licences.
It has no expiry. It works until an owner or admin revokes it in Settings → API keys, or until the person is deactivated, un-ticked or removed.
The secret is shown once. Everything done with the key is recorded against the person and the key.

Quickstart

Plain HTTPS with a Bearer key. List your open tickets:

$ export SAUTIDESK_KEY=<your API key>

curl -sS "https://api.sautidesk.com/v1/desk/tickets?tab=mine&limit=25" \
  -H "Authorization: Bearer $SAUTIDESK_KEY"

Endpoints by Resource

Select any operation below to inspect path parameters, request payloads and code examples.

Authentication

API keys. Only workspace owners and admins issue them: each key acts as the person it was issued for, and the issuer picks the most it may do. Owners and admins list and revoke every key.

GET/v1/desk/api-keys

List every API keydesk.admin

POST/v1/desk/api-keys

Issue an API keydesk.admin

DELETE/v1/desk/api-keys/{id}

Revoke an API keydesk.admin

GET/v1/desk/api-keys/{id}/issued

List the keys a key issueddesk.admin

GET/v1/desk/api-keys/people

List who you can issue a key fordesk.admin

Tickets

Open, list, read, assign, resolve and follow up tickets across calls, WhatsApp, SMS, email and web chat, and add or remove the people following a ticket.

GET/v1/desk/tickets

List ticketsdesk.read

POST/v1/desk/tickets

Open a ticketdesk.write

GET/v1/desk/tickets/{id}

Get a ticketdesk.read

PATCH/v1/desk/tickets/{id}

Update a ticketdesk.write

POST/v1/desk/tickets/{id}/assign

Assign a ticketdesk.write

POST/v1/desk/tickets/{id}/follow-up

Open a follow-up ticketdesk.write

POST/v1/desk/tickets/{id}/notes

Add an internal note to a ticketdesk.write

GET/v1/desk/tickets/{id}/participants

List a ticket's participantsdesk.read

POST/v1/desk/tickets/{id}/participants

Add a participant to a ticketdesk.write

DELETE/v1/desk/tickets/{id}/participants/{uid}

Remove a participant from a ticketdesk.write

POST/v1/desk/tickets/{id}/resolve

Resolve a ticketdesk.write

GET/v1/desk/tickets/counts

Count tickets by tabdesk.read

Activities

The entries on a ticket's timeline (messages, calls, emails), each pointing at its ticket, and the private team comments on them with attachments.

GET/v1/desk/activities

List a ticket's activitiesdesk.read

GET/v1/desk/activities/{id}

Get an activitydesk.read

GET/v1/desk/activities/{id}/comments

List comments on an activitydesk.read

POST/v1/desk/activities/{id}/comments

Add a comment to an activitydesk.write

PATCH/v1/desk/activities/{id}/comments/{cid}

Edit a commentdesk.write

DELETE/v1/desk/activities/{id}/comments/{cid}

Delete a commentdesk.write

GET/v1/desk/activities/{id}/comments/{cid}/attachments/{uid}

Download a comment attachmentdesk.read

POST/v1/desk/activities/{id}/comments/uploads

Stage a comment attachmentdesk.write

GET/v1/desk/activities/{id}/html

Get a message's HTML bodydesk.read

GET/v1/desk/activities/{id}/media

Get a message's media filedesk.read

PATCH/v1/desk/activities/{id}/outcome

Set a call's outcomedesk.write

Messages

The one way to message a customer by SMS, WhatsApp or email: send to a number or an address and the message lands on the person's open ticket, or opens one. Sending to an existing contact is POST /v1/desk/contacts/{id}/messages, in Contacts.

POST/v1/desk/messages

Send a message to a number or emaildesk.write

Contacts

The address book: contacts, their phone numbers and emails, duplicates, merge, history and the bin.

GET/v1/desk/bin

List the bindesk.read

POST/v1/desk/bin/{id}/restore

Restore from the bindesk.write

GET/v1/desk/contacts

List contactsdesk.read

POST/v1/desk/contacts

Find or create a contactdesk.write

GET/v1/desk/contacts/{id}

Get a contactdesk.read

PATCH/v1/desk/contacts/{id}

Update a contactdesk.write

DELETE/v1/desk/contacts/{id}

Delete a contactdesk.write

POST/v1/desk/contacts/{id}/chat/typing

Signal that you are typing in web chatdesk.write

GET/v1/desk/contacts/{id}/duplicates

Find duplicates of a contactdesk.read

POST/v1/desk/contacts/{id}/emails

Add an email to a contactdesk.write

PATCH/v1/desk/contacts/{id}/emails/{eid}

Edit a contact's emaildesk.write

DELETE/v1/desk/contacts/{id}/emails/{eid}

Remove a contact's emaildesk.write

POST/v1/desk/contacts/{id}/merge

Merge a contact into anotherdesk.write

POST/v1/desk/contacts/{id}/messages

Send a message to a contactdesk.write

POST/v1/desk/contacts/{id}/numbers

Add a phone number to a contactdesk.write

PATCH/v1/desk/contacts/{id}/numbers/{nid}

Edit a contact's phone numberdesk.write

DELETE/v1/desk/contacts/{id}/numbers/{nid}

Remove a contact's phone numberdesk.write

GET/v1/desk/contacts/{id}/search

Search within a contact's historydesk.read

GET/v1/desk/contacts/{id}/tickets

List a contact's ticketsdesk.read

GET/v1/desk/contacts/{id}/timeline

Get a contact's timelinedesk.read

POST/v1/desk/contacts/{id}/whatsapp/typing

Signal that you are typing on WhatsAppdesk.write

GET/v1/desk/contacts/{id}/whatsapp/window

Get the WhatsApp reply windowdesk.read

GET/v1/desk/contacts/duplicates

List possible duplicate contactsdesk.read

POST/v1/desk/contacts/duplicates/dismiss

Dismiss duplicate contactsdesk.write

GET/v1/desk/search

Search tickets and contactsdesk.read

Calls and phone

The softphone line, presence, registered devices, call transfer and wrap-up for the signed-in person.

POST/v1/desk/calls

Place a calldesk.write

POST/v1/desk/calls/{id}/wrap

Wrap up a calldesk.write

POST/v1/desk/calls/transfer

Transfer a calldesk.write

GET/v1/desk/phone/devices

List registered phone devicesdesk.read

DELETE/v1/desk/phone/devices/{id}

Remove a phone devicedesk.write

POST/v1/desk/phone/presence

DELETE/v1/desk/phone/presence

Clear softphone presencedesk.write

GET/v1/desk/phone/token

Get a softphone tokendesk.read

People and presence

The team roster, each person's availability state and and ring settings.

GET/v1/desk/agents

List peopledesk.read

GET/v1/desk/agents/{id}/avatar

Get a person's avatardesk.read

PUT/v1/desk/agents/{id}/ring

Set where a person's calls ringdesk.admin

PUT/v1/desk/agents/me/state

Set my availabilitydesk.write

GET/v1/desk/stats/me

Get my statsdesk.read

Tasks

Follow-ups and callbacks attached to tickets and calls.

GET/v1/desk/tasks

List tasksdesk.read

POST/v1/desk/tasks

Create a taskdesk.write

PATCH/v1/desk/tasks/{id}

Update a taskdesk.write

POST/v1/desk/tasks/{id}/done

Mark a task donedesk.write

Direct messages, notifications and live events

Team direct messages, the notification bell, supervisor nudges, and the live server-sent event stream.

GET/v1/desk/dm/threads

List direct-message threadsdesk.read

POST/v1/desk/dm/threads

Start a direct-message threaddesk.write

POST/v1/desk/dm/threads/{id}/attachments

Upload a direct-message attachmentdesk.write

GET/v1/desk/dm/threads/{id}/messages

List a thread's messagesdesk.read

POST/v1/desk/dm/threads/{id}/messages

Send a direct messagedesk.write

GET/v1/desk/dm/threads/{id}/messages/{mid}/attachments/{uid}

Download a direct-message attachmentdesk.read

GET/v1/desk/nudges

List nudgesdesk.read

POST/v1/desk/nudgesPRO

Nudge an agentdesk.supervise

POST/v1/desk/nudges/{id}/seen

Mark a nudge seendesk.write

GET/v1/desk/stream

Stream live eventsdesk.read

Reports (Pro)

Supervisor and executive reports, scheduled report emails and report exports. Requires SautiDesk Pro and the desk.supervise scope.

GET/v1/desk/reports/availabilityPRO

Availability reportdesk.supervise

GET/v1/desk/reports/availability/atPRO

Availability at a moment in timedesk.supervise

GET/v1/desk/reports/callsPRO

Calls reportdesk.supervise

GET/v1/desk/reports/calls-summaryPRO

Calls channel reportdesk.supervise

GET/v1/desk/reports/contactsPRO

Contacts reportdesk.supervise

GET/v1/desk/reports/costPRO

Cost reportdesk.supervise

GET/v1/desk/reports/dayPRO

Day reportdesk.supervise

GET/v1/desk/reports/emailPRO

Email channel reportdesk.supervise

GET/v1/desk/reports/exportPRO

List report exportsdesk.supervise

POST/v1/desk/reports/exportPRO

Start a report exportdesk.supervise

GET/v1/desk/reports/export/{id}PRO

Get a report exportdesk.supervise

GET/v1/desk/reports/forecastPRO

Forecast reportdesk.supervise

GET/v1/desk/reports/hourlyPRO

Hourly reportdesk.supervise

GET/v1/desk/reports/leaguePRO

League table reportdesk.supervise

GET/v1/desk/reports/missedPRO

Missed calls reportdesk.supervise

GET/v1/desk/reports/numbersPRO

Numbers reportdesk.supervise

GET/v1/desk/reports/occupancyPRO

Occupancy reportdesk.supervise

GET/v1/desk/reports/owedPRO

Owed replies reportdesk.supervise

GET/v1/desk/reports/reasonsPRO

Reasons reportdesk.supervise

GET/v1/desk/reports/recordedPRO

Recorded calls reportdesk.supervise

GET/v1/desk/reports/repeatPRO

Repeat callers reportdesk.supervise

GET/v1/desk/reports/repliesPRO

Replies reportdesk.supervise

GET/v1/desk/reports/scorecardPRO

Scorecard reportdesk.supervise

GET/v1/desk/reports/servicePRO

Service level reportdesk.supervise

GET/v1/desk/reports/smsPRO

SMS channel reportdesk.supervise

GET/v1/desk/reports/spendPRO

Spend reportdesk.supervise

GET/v1/desk/reports/staffingPRO

Staffing reportdesk.supervise

GET/v1/desk/reports/subscriptionsPRO

List report subscriptionsdesk.supervise

POST/v1/desk/reports/subscriptionsPRO

Create a report subscriptiondesk.supervise

PATCH/v1/desk/reports/subscriptions/{id}PRO

Update a report subscriptiondesk.supervise

DELETE/v1/desk/reports/subscriptions/{id}PRO

Delete a report subscriptiondesk.supervise

POST/v1/desk/reports/subscriptions/{id}/sendPRO

Send a report subscription nowdesk.supervise

GET/v1/desk/reports/ticketsPRO

Tickets reportdesk.supervise

GET/v1/desk/reports/transfersPRO

Transfers reportdesk.supervise

GET/v1/desk/reports/webchatPRO

Web chat reportdesk.supervise

GET/v1/desk/reports/weekPRO

Week reportdesk.supervise

GET/v1/desk/reports/whatsappPRO

WhatsApp channel reportdesk.supervise

GET/v1/desk/settings/service-levelPRO

Get the service-level targetdesk.supervise

PUT/v1/desk/settings/service-levelPRO

Set the service-level targetdesk.admin

Channels and templates

SMS, WhatsApp, email and web chat settings, sender IDs, and message templates.

GET/v1/desk/mail/addresses

List email addressesdesk.read

POST/v1/desk/mail/addresses

Add an email addressdesk.admin

PATCH/v1/desk/mail/addresses/{id}

Update an email addressdesk.admin

DELETE/v1/desk/mail/addresses/{id}

Remove an email addressdesk.admin

GET/v1/desk/mail/attachments/{id}

Download an email attachmentdesk.read

GET/v1/desk/mail/domains

List email domainsdesk.read

POST/v1/desk/mail/domains

Add an email domaindesk.admin

DELETE/v1/desk/mail/domains/{id}

Remove an email domaindesk.admin

GET/v1/desk/mail/domains/{id}/setup

Get an email domain's DNS setupdesk.admin

POST/v1/desk/mail/domains/{id}/verify

Verify an email domaindesk.admin

GET/v1/desk/mail/settings

Get email settingsdesk.read

PUT/v1/desk/mail/settings

Set email settingsdesk.admin

POST/v1/desk/mail/uploads

Stage an email attachmentdesk.write

GET/v1/desk/sender-ids

List SMS sender IDsdesk.read

POST/v1/desk/sender-ids

Request an SMS sender IDdesk.admin

GET/v1/desk/sms/settings

Get SMS settingsdesk.admin

PUT/v1/desk/sms/settings

Set SMS settingsdesk.admin

GET/v1/desk/templates

List templatesdesk.read

POST/v1/desk/templates

Create a templatedesk.admin

GET/v1/desk/templates/{id}

Get a templatedesk.read

PATCH/v1/desk/templates/{id}

Update a templatedesk.admin

DELETE/v1/desk/templates/{id}

Delete a templatedesk.admin

POST/v1/desk/templates/{id}/clone

Clone a templatedesk.admin

POST/v1/desk/templates/{id}/submit

Submit a template to Metadesk.admin

POST/v1/desk/templates/{id}/sync

Sync a template's approval statusdesk.admin

POST/v1/desk/templates/active

Switch templates on or offdesk.admin

GET/v1/desk/templates/starters

List starter templatesdesk.read

POST/v1/desk/templates/starters/{key}/activate

Install a starter templatedesk.admin

GET/v1/desk/whatsapp/numbers

List WhatsApp numbersdesk.read

GET/v1/desk/whatsapp/settings

Get WhatsApp settingsdesk.read

PUT/v1/desk/whatsapp/settings

Set WhatsApp settingsdesk.admin

GET/v1/desk/widget/settings

Get web chat widget settingsdesk.admin

PUT/v1/desk/widget/settings

Set web chat widget settingsdesk.admin

PUT/v1/desk/widget/voice

Set the widget call buttondesk.admin

Workspace configuration

Queues, categories, outcomes, the phone menu, numbers and routing, holidays and the workspace activity log.

GET/v1/desk/admin/activity

List the activity logdesk.admin

GET/v1/desk/admin/activity-settings

Get activity log settingsdesk.admin

PATCH/v1/desk/admin/activity-settings

Update activity log settingsdesk.admin

GET/v1/desk/admin/dashboard

Get the admin dashboarddesk.admin

GET/v1/desk/categories

List ticket categoriesdesk.read

POST/v1/desk/categories

Create a categorydesk.admin

PATCH/v1/desk/categories/{id}

Update a categorydesk.admin

DELETE/v1/desk/categories/{id}

Delete a categorydesk.admin

GET/v1/desk/config

Get workspace configurationdesk.read

GET/v1/desk/holidays

List holidaysdesk.read

POST/v1/desk/holidays

Create a holidaydesk.admin

PATCH/v1/desk/holidays/{id}

Update a holidaydesk.admin

DELETE/v1/desk/holidays/{id}

Delete a holidaydesk.admin

POST/v1/desk/holidays/seed

Seed public holidaysdesk.admin

GET/v1/desk/members

List workspace membersdesk.read

GET/v1/desk/menu

Get the phone menudesk.read

PUT/v1/desk/menu

Set the phone menudesk.admin

DELETE/v1/desk/menu

Remove the phone menudesk.admin

GET/v1/desk/numbers

List your phone numbersdesk.read

POST/v1/desk/numbers/{id}/activate

Let Desk answer a numberdesk.admin

DELETE/v1/desk/numbers/{id}/activate

Stop Desk answering a numberdesk.admin

POST/v1/desk/numbers/{id}/claim

Buy a numberdesk.admin

POST/v1/desk/numbers/{id}/hold

Hold a number for 30 minutesdesk.admin

DELETE/v1/desk/numbers/{id}/hold

Release a held numberdesk.admin

PUT/v1/desk/numbers/{id}/routing

Set a number's routingdesk.admin

DELETE/v1/desk/numbers/{id}/routing

Clear a number's routingdesk.admin

GET/v1/desk/numbers/available

List numbers you can buydesk.admin

GET/v1/desk/outcomes

List outcomesdesk.read

POST/v1/desk/outcomes

Create an outcomedesk.admin

PATCH/v1/desk/outcomes/{id}

Update an outcomedesk.admin

DELETE/v1/desk/outcomes/{id}

Delete an outcomedesk.admin

PUT/v1/desk/outcomes/order

Reorder ticket outcomesdesk.admin

GET/v1/desk/queues

List queuesdesk.read

POST/v1/desk/queues

Create a queuedesk.admin

PATCH/v1/desk/queues/{id}

Update a queuedesk.admin

DELETE/v1/desk/queues/{id}

Delete a queuedesk.admin

Webhooks

Get a signed HTTPS call to your server when something happens in the desk: a ticket opens, a message arrives, a call is missed. Workspace owners and admins manage endpoints here or in Settings > Webhooks. Every event uses one envelope, described below.

The event envelope

Every event, in every delivery, in Settings > Dashboard > Logs, has this shape. datais a snapshot of the thing the event is about, shaped like the API's own object for it.

id	string (uuid)	Unique id of the event. The same id is used in the Logs view and on every retry, so use it to de-duplicate.
type	string	The event type, for example ticket.opened.
created_at	string (RFC 3339)	When the event happened.
workspace_id	string (uuid)	The workspace the event belongs to.
actor	object	Who did it: type is person, customer or system; id and name when known.
data	object	A snapshot of the resource, shaped like the API's own object for it (see each event).

Verify the signature

Compute HMAC-SHA256 over the raw request body, a dot, and the t value, using the signing secret (whsec_...) as the key. Compare the hex digest with v1 in constant time. Reject a t more than five minutes old.

X-Sautikit-Signature	t=<unix seconds>,v1=<hex HMAC-SHA256 of "<raw body>.<t>" keyed with your signing secret>.
X-Sautikit-Timestamp	The same t, as unix seconds.
X-Sautikit-Event-Id	The envelope's id.
X-Sautikit-Event-Kind	The envelope's type.
X-Sautikit-Delivery-Id	Id of this delivery; the same on every retry.
X-Sautikit-Attempt	1 for the first attempt, then 2, 3 ... up to 8.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody + "." + parts.t)
    .digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return ok && fresh;
}

A delivery answered with anything but 2xx is retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours and 24 hours (8 attempts), then marked dead_letter. Retry it by hand from Settings > Webhooks or POST /v1/desk/webhooks/{id}/deliveries/{did}/retry.

Tickets events

ticket.opened

A new ticket was opened (an inbound message or call, or an agent starting one). Tickets never reopen: a customer who comes back gets a follow-up ticket, and data.follows_id and data.follows_ref name the ticket it follows (null when it follows nothing).

data is a ticket.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket.opened",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ref": "TCK-4471",
    "subject": "Wrong part supplied",
    "channel": "whatsapp",
    "category": "Billing",
    "status": "open",
    "owner": "Amina Hassan",
    "owner_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "follows_id": null,
    "follows_ref": null,
    "queue_id": "",
    "queue_name": "",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "contact_email": "mary@example.com",
    "opened_at": "2026-10-14T08:15:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "closed_at": null,
    "widget_seen_at": null,
    "last_customer_at": "2026-10-14T08:15:00Z",
    "last_outcome": null,
    "last_outcome_activity_id": null,
    "ticket_outcome": "",
    "last_call_leg_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

ticket.assigned

A ticket was given to a person.

data is a ticket.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket.assigned",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ref": "TCK-4471",
    "subject": "Wrong part supplied",
    "channel": "whatsapp",
    "category": "Billing",
    "status": "open",
    "owner": "Amina Hassan",
    "owner_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "follows_id": null,
    "follows_ref": null,
    "queue_id": "",
    "queue_name": "",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "contact_email": "mary@example.com",
    "opened_at": "2026-10-14T08:15:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "closed_at": null,
    "widget_seen_at": null,
    "last_customer_at": "2026-10-14T08:15:00Z",
    "last_outcome": null,
    "last_outcome_activity_id": null,
    "ticket_outcome": "",
    "last_call_leg_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

ticket.replied

An agent replied to the customer on a ticket (internal notes do not count).

data is a ticket.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket.replied",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ref": "TCK-4471",
    "subject": "Wrong part supplied",
    "channel": "whatsapp",
    "category": "Billing",
    "status": "open",
    "owner": "Amina Hassan",
    "owner_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "follows_id": null,
    "follows_ref": null,
    "queue_id": "",
    "queue_name": "",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "contact_email": "mary@example.com",
    "opened_at": "2026-10-14T08:15:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "closed_at": null,
    "widget_seen_at": null,
    "last_customer_at": "2026-10-14T08:15:00Z",
    "last_outcome": null,
    "last_outcome_activity_id": null,
    "ticket_outcome": "",
    "last_call_leg_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

ticket.resolved

A ticket was resolved.

data is a ticket.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket.resolved",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ref": "TCK-4471",
    "subject": "Wrong part supplied",
    "channel": "whatsapp",
    "category": "Billing",
    "status": "open",
    "owner": "Amina Hassan",
    "owner_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "follows_id": null,
    "follows_ref": null,
    "queue_id": "",
    "queue_name": "",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "contact_email": "mary@example.com",
    "opened_at": "2026-10-14T08:15:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "closed_at": null,
    "widget_seen_at": null,
    "last_customer_at": "2026-10-14T08:15:00Z",
    "last_outcome": null,
    "last_outcome_activity_id": null,
    "ticket_outcome": "",
    "last_call_leg_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

Messages events

message.received

A customer message arrived, on any channel (see data.channel: email, sms, whatsapp, widget).

data is a message.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "message.received",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "customer",
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri"
  },
  "data": {
    "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "kind": "message",
    "channel": "whatsapp",
    "direction": "in",
    "author": "Mary Njeri",
    "body": "Hello, the part you sent does not fit.",
    "subject": "",
    "occurred_at": "2026-10-14T08:15:00Z",
    "local_address": "+254709221583",
    "remote_address": "+254722145900",
    "delivery": "none",
    "delivery_error": ""
  }
}

message.sent

An agent sent a message to the customer, on any channel.

data is a message.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "message.sent",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "kind": "message",
    "channel": "whatsapp",
    "direction": "in",
    "author": "Mary Njeri",
    "body": "Hello, the part you sent does not fit.",
    "subject": "",
    "occurred_at": "2026-10-14T08:15:00Z",
    "local_address": "+254709221583",
    "remote_address": "+254722145900",
    "delivery": "none",
    "delivery_error": ""
  }
}

Calls events

call.ringing

A call leg started ringing (inbound to the desk, or an agent dialling out). Sent once per leg. data has no outcome, answered_at or ended_at yet: the call is still ringing.

data is a call.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "call.ringing",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "customer",
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri"
  },
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "call_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "agent_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "agent_name": "Amina Hassan",
    "direction": "inbound",
    "outcome": "answered",
    "queue_name": "Support",
    "desk_number": "+254709221583",
    "arrived_at": "2026-10-14T08:10:00Z",
    "queued_at": "2026-10-14T08:10:02Z",
    "answered_at": "2026-10-14T08:10:20Z",
    "ended_at": "2026-10-14T08:14:05Z",
    "hold_seconds": 0,
    "recording_seconds": 225,
    "duration_seconds": 245,
    "talk_seconds": 225
  }
}

call.answered

The far end picked up. Sent once per leg, at the moment of the answer: data.answered_at is when the other party answered (for an outbound call, not when it was dialled), data.outcome is "answered" and data.ended_at is not present yet. Never sent for a call nobody answered.

data is a call.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "call.answered",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "call_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "agent_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "agent_name": "Amina Hassan",
    "direction": "inbound",
    "outcome": "answered",
    "queue_name": "Support",
    "desk_number": "+254709221583",
    "arrived_at": "2026-10-14T08:10:00Z",
    "queued_at": "2026-10-14T08:10:02Z",
    "answered_at": "2026-10-14T08:10:20Z",
    "ended_at": "2026-10-14T08:14:05Z",
    "hold_seconds": 0,
    "recording_seconds": 225,
    "duration_seconds": 245,
    "talk_seconds": 225
  }
}

call.ended

A call that was answered, or an outbound call that was not, is over. Sent once per leg, only when it has ended: data.ended_at is set, data.outcome says how (answered, transferred, or for an unanswered outbound call no_answer, busy or failed) and data.duration_seconds and data.talk_seconds are filled. An unanswered INBOUND call is call.missed instead, not call.ended.

data is a call.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "call.ended",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "call_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "agent_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "agent_name": "Amina Hassan",
    "direction": "inbound",
    "outcome": "answered",
    "queue_name": "Support",
    "desk_number": "+254709221583",
    "arrived_at": "2026-10-14T08:10:00Z",
    "queued_at": "2026-10-14T08:10:02Z",
    "answered_at": "2026-10-14T08:10:20Z",
    "ended_at": "2026-10-14T08:14:05Z",
    "hold_seconds": 0,
    "recording_seconds": 225,
    "duration_seconds": 245,
    "talk_seconds": 225
  }
}

call.missed

An inbound call nobody answered (abandoned, no answer, busy, failed, voicemail or dropped in the menu). Sent once per leg, when it ends, instead of call.ended and never together with call.answered. An outbound call that was not answered is a call.ended with outcome no_answer, busy or failed.

data is a call.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "call.missed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "customer",
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri"
  },
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "call_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "contact_number": "+254722145900",
    "agent_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "agent_name": "Amina Hassan",
    "direction": "inbound",
    "outcome": "answered",
    "queue_name": "Support",
    "desk_number": "+254709221583",
    "arrived_at": "2026-10-14T08:10:00Z",
    "queued_at": "2026-10-14T08:10:02Z",
    "answered_at": "2026-10-14T08:10:20Z",
    "ended_at": "2026-10-14T08:14:05Z",
    "hold_seconds": 0,
    "recording_seconds": 225,
    "duration_seconds": 245,
    "talk_seconds": 225
  }
}

Contacts events

contact.created

A contact was created.

data is a contact.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "contact.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system"
  },
  "data": {
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri",
    "company": "Njeri Hardware",
    "address": "Moi Avenue, Nairobi",
    "notes": "Prefers WhatsApp.",
    "blocked": false,
    "account_no": "ACC-1042",
    "consent_bulk_sms": true,
    "consent_bulk_whatsapp": true,
    "consent_newsletters": true,
    "consent_marketing_calls": true,
    "numbers": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
        "e164": "+254722145900",
        "label": "",
        "primary": true
      }
    ],
    "emails": [
      {
        "id": "e1f2a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7",
        "address": "mary@example.com",
        "label": "",
        "primary": true
      }
    ]
  }
}

contact.updated

A contact's details changed (name, company, address, notes, account number, consent or blocked).

data is a contact.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "contact.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system"
  },
  "data": {
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri",
    "company": "Njeri Hardware",
    "address": "Moi Avenue, Nairobi",
    "notes": "Prefers WhatsApp.",
    "blocked": false,
    "account_no": "ACC-1042",
    "consent_bulk_sms": true,
    "consent_bulk_whatsapp": true,
    "consent_newsletters": true,
    "consent_marketing_calls": true,
    "numbers": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
        "e164": "+254722145900",
        "label": "",
        "primary": true
      }
    ],
    "emails": [
      {
        "id": "e1f2a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7",
        "address": "mary@example.com",
        "label": "",
        "primary": true
      }
    ]
  }
}

contact.merged

Two contacts were merged. data is the surviving contact.

data is a contact.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "contact.merged",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "name": "Mary Njeri",
    "company": "Njeri Hardware",
    "address": "Moi Avenue, Nairobi",
    "notes": "Prefers WhatsApp.",
    "blocked": false,
    "account_no": "ACC-1042",
    "consent_bulk_sms": true,
    "consent_bulk_whatsapp": true,
    "consent_newsletters": true,
    "consent_marketing_calls": true,
    "numbers": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
        "e164": "+254722145900",
        "label": "",
        "primary": true
      }
    ],
    "emails": [
      {
        "id": "e1f2a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7",
        "address": "mary@example.com",
        "label": "",
        "primary": true
      }
    ]
  }
}

Tasks events

task.created

A task (callback, follow-up) was scheduled.

data is a task.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "task.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "3c4d5e6f-7081-4923-8a4b-5c6d7e8f9012",
    "kind": "callback",
    "note": "Call back about the invoice",
    "due_at": "2026-10-14T14:00:00Z",
    "status": "open",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "assignee_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "assignee_name": "Amina Hassan",
    "created_by": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "created_at": "2026-10-14T08:20:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "completed_at": null,
    "contact_number": "+254722145900",
    "desk_number": "+254709221583"
  }
}

task.due

An open task reached its due time.

data is a task.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "task.due",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system"
  },
  "data": {
    "id": "3c4d5e6f-7081-4923-8a4b-5c6d7e8f9012",
    "kind": "callback",
    "note": "Call back about the invoice",
    "due_at": "2026-10-14T14:00:00Z",
    "status": "open",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "assignee_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "assignee_name": "Amina Hassan",
    "created_by": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "created_at": "2026-10-14T08:20:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "completed_at": null,
    "contact_number": "+254722145900",
    "desk_number": "+254709221583"
  }
}

task.done

A task was completed.

data is a task.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "task.done",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "id": "3c4d5e6f-7081-4923-8a4b-5c6d7e8f9012",
    "kind": "callback",
    "note": "Call back about the invoice",
    "due_at": "2026-10-14T14:00:00Z",
    "status": "open",
    "ticket_id": "0b1c7d3e-5a2f-4c68-9d21-6a4f0e9b7c10",
    "ticket_ref": "TCK-4471",
    "contact_id": "c1d2e3f4-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
    "contact_name": "Mary Njeri",
    "assignee_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "assignee_name": "Amina Hassan",
    "created_by": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "created_at": "2026-10-14T08:20:00Z",
    "updated_at": "2026-10-14T08:20:00Z",
    "completed_at": null,
    "contact_number": "+254722145900",
    "desk_number": "+254709221583"
  }
}

Wallet events

wallet.topped_up

A top-up was credited to the workspace wallet (card, M-Pesa or automatic). data carries the amount, the new balance and the currency; never a card or payment detail.

data is the sentence the Logs view shows (summary), the thing it names (subject, when there is one) and the fields below. Secrets, card details and key values are never included. Only your Owners and Admins see these events in the Logs view; they reach the webhook endpoints you set up here.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.topped_up",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The wallet was topped up with KES 1,000.00",
    "amount_minor": 100000,
    "currency": "KES",
    "balance_minor": 245000,
    "provider": "paystack"
  }
}

wallet.low_balance

The wallet balance fell to or below the low-balance threshold the workspace set. Sent once a day at most while it stays low.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.low_balance",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The wallet balance is low: KES 180.00 (alert at KES 500.00)",
    "balance_minor": 18000,
    "currency": "KES",
    "threshold_minor": 50000
  }
}

wallet.depleted

A charge took the wallet balance to zero or below. Calls and other charges can be refused until the wallet is topped up.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.depleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The wallet balance ran out: KES -12.00",
    "balance_minor": -1200,
    "currency": "KES"
  }
}

wallet.autopay_succeeded

An automatic top-up charged the saved card and credited the wallet.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.autopay_succeeded",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "An automatic top-up of KES 2,000.00 was credited",
    "amount_minor": 200000,
    "currency": "KES",
    "balance_minor": 245000
  }
}

wallet.autopay_action_required

The card's bank wants the cardholder to approve an automatic top-up before it can go through.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.autopay_action_required",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "An automatic top-up needs the cardholder's approval",
    "amount_minor": 200000,
    "currency": "KES"
  }
}

wallet.autopay_disabled

Automatic top-ups were switched off by the platform (repeated failures), not by a person.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "wallet.autopay_disabled",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "Automatic top-ups were switched off after repeated failures",
    "reason": "repeated_failures"
  }
}

Numbers and channels events

number.claimed

A phone number was bought from the workspace wallet (in the console or with an API key).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.claimed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina bought the number +254712345678 from the workspace wallet",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    },
    "e164": "+254712345678",
    "total_minor": 116000,
    "currency": "KES"
  }
}

number.released

A phone number was released: by an admin, because its rental went unpaid, or because a trial ended. data.reason says which when the platform did it.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.released",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The number +254712345678 was released",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    },
    "e164": "+254712345678",
    "reason": "rental_past_due"
  }
}

number.renamed

A phone number's friendly name changed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.renamed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina renamed +254712345678 to \"Sales line\"",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    },
    "from": "",
    "to": "Sales line"
  }
}

number.routing_changed

How a Desk number is answered was changed or cleared.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.routing_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina changed how +254712345678 is answered",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    }
  }
}

number.desk_enabled

SautiDesk was turned on for a phone number.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.desk_enabled",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina turned Desk on for +254712345678",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    }
  }
}

number.desk_disabled

SautiDesk was turned off for a phone number.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "number.desk_disabled",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina turned Desk off for +254712345678",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    }
  }
}

email_domain.added

A mail domain was added for sending and receiving email. Its DNS records may still be pending.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "email_domain.added",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the mail domain example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "domain": "example.com",
    "status": "pending"
  }
}

email_domain.verified

A mail domain's DNS records were verified: it can now send email. Sent once per domain.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "email_domain.verified",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The mail domain example.com is verified and can send email",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "domain": "example.com",
    "status": "verified",
    "receiving": "verified"
  }
}

email_domain.removed

A mail domain was removed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "email_domain.removed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina removed the mail domain example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "domain": "example.com"
  }
}

sender_id.requested

An SMS sender ID (the name SMS arrive from) was requested. The carrier decides in a few days.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "sender_id.requested",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina requested the SMS sender ID ACMELTD",
    "subject": {
      "ref": "",
      "name": "ACMELTD"
    },
    "sender_id": "ACMELTD",
    "request_id": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "requested"
  }
}

sender_id.approved

An SMS sender ID was approved: the workspace can send SMS as that name.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "sender_id.approved",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The SMS sender ID ACMELTD was approved",
    "subject": {
      "ref": "",
      "name": "ACMELTD"
    },
    "sender_id": "ACMELTD",
    "request_id": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "approved"
  }
}

sender_id.rejected

An SMS sender ID was refused by the carrier. data.note gives the reason when there is one.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "sender_id.rejected",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The SMS sender ID ACMELTD was refused",
    "subject": {
      "ref": "",
      "name": "ACMELTD"
    },
    "sender_id": "ACMELTD",
    "request_id": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "rejected",
    "note": "Try a different name."
  }
}

widget.settings_changed

The web chat widget's settings changed (switched on or off, allowed origins, look). data.enabled says whether it is on now.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "widget.settings_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina switched the web chat widget on",
    "enabled": true
  }
}

whatsapp.connected

WhatsApp was switched on in SautiDesk for a connected number: that number now carries the desk's WhatsApp conversations.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "whatsapp.connected",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina switched WhatsApp on for +254712345678",
    "subject": {
      "ref": "",
      "name": "+254712345678"
    },
    "e164": "+254712345678"
  }
}

whatsapp.disconnected

WhatsApp was switched off in SautiDesk: no number carries the desk's WhatsApp conversations any more.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "whatsapp.disconnected",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina switched WhatsApp off"
  }
}

menu.saved

The phone menu (press 1 for ...) was saved.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "menu.saved",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina saved the phone menu"
  }
}

menu.deleted

The phone menu was removed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "menu.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina removed the phone menu"
  }
}

Reports events

report_subscription.created

Somebody subscribed to a scheduled emailed report.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report_subscription.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina subscribed to the Calls report (weekly)",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "subscription_id": "3d4e5f60-7182-4a93-8b4c-5d6e7f809102",
    "report": "calls",
    "frequency": "weekly",
    "format": "csv",
    "recipients": 2
  }
}

report_subscription.updated

A report subscription was changed (report, schedule, format or recipients).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report_subscription.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina changed the Calls report subscription",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "subscription_id": "3d4e5f60-7182-4a93-8b4c-5d6e7f809102",
    "report": "calls",
    "frequency": "daily",
    "format": "csv",
    "recipients": 2
  }
}

report_subscription.deleted

A report subscription was deleted.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report_subscription.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the Calls report subscription",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "subscription_id": "3d4e5f60-7182-4a93-8b4c-5d6e7f809102",
    "report": "calls"
  }
}

report.sent

A scheduled report was emailed to its recipients (on schedule or with Send now). data.recipients is a count; addresses are not included.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report.sent",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The Calls report was emailed to 2 people",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "subscription_id": "3d4e5f60-7182-4a93-8b4c-5d6e7f809102",
    "report": "calls",
    "format": "csv",
    "range_from": "2026-10-07",
    "range_to": "2026-10-13",
    "recipients": 2
  }
}

report.send_failed

A scheduled report could not be emailed (to every recipient, or to some). It is tried again at the next slot.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report.send_failed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "The Calls report could not be emailed",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "subscription_id": "3d4e5f60-7182-4a93-8b4c-5d6e7f809102",
    "report": "calls",
    "error": "The mail provider did not accept the message."
  }
}

report.downloaded

A report was downloaded as a CSV file through the API or the console. A file fetched later from an export link goes straight from storage and is not seen.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "report.downloaded",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina downloaded the Calls report (CSV)",
    "subject": {
      "ref": "",
      "name": "Calls"
    },
    "report": "calls",
    "format": "csv",
    "range_from": "2026-10-07",
    "range_to": "2026-10-13"
  }
}

Team and plan events

member.invited

Somebody was invited to SautiDesk; the seat is billable from the invitation.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.invited",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina invited bruce@example.com to SautiDesk; the seat is billable from now",
    "subject": {
      "ref": "",
      "name": "bruce@example.com"
    }
  }
}

member.joined

An invited person accepted and joined the workspace.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.joined",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "Bruce Otieno joined the workspace",
    "subject": {
      "ref": "",
      "name": "Bruce Otieno"
    },
    "member_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "role": "member"
  }
}

member.role_changed

A member's role changed (owner, admin, member or viewer).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.role_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina made Bruce an admin",
    "subject": {
      "ref": "",
      "name": "Bruce Otieno"
    },
    "member_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "role": "admin",
    "from_role": "member"
  }
}

member.removed

A member was removed from the workspace.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.removed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina removed Bruce from the workspace",
    "subject": {
      "ref": "",
      "name": "Bruce Otieno"
    },
    "member_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33"
  }
}

member.licence_changed

A member was given or lost a licence (Converse, Contacts or Supervisor).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.licence_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina gave Bruce the Converse licence",
    "subject": {
      "ref": "",
      "name": "Bruce Otieno"
    }
  }
}

member.seat_changed

A member was made active on SautiDesk (a billable seat) or taken off it.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "member.seat_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina made Bruce active on SautiDesk",
    "subject": {
      "ref": "",
      "name": "Bruce Otieno"
    }
  }
}

plan.changed

The workspace's SautiDesk plan changed (Basic to Pro, or back).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "plan.changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina moved the workspace to the Pro plan",
    "plan": "pro",
    "from_plan": "basic"
  }
}

API keys and webhooks events

api_key.issued

An API key was issued for a member. The key's value is never in an event.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "api_key.issued",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina issued a token for Bruce",
    "token_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "label": "Zapier",
    "member_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "scopes": [
      "desk.read",
      "desk.write"
    ]
  }
}

api_key.revoked

An API key was revoked (data.cascade is true when the keys it issued were revoked with it).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "api_key.revoked",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina revoked a key for Bruce",
    "token_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "label": "Zapier",
    "member_id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "cascade": false
  }
}

webhook.created

A webhook endpoint was added. data.host is the host of its URL, never the whole URL.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "webhook.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added a webhook for example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "endpoint_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "host": "example.com"
  }
}

webhook.updated

A webhook endpoint was changed (URL, events or switched on or off).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "webhook.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina changed the webhook for example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "endpoint_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "host": "example.com"
  }
}

webhook.deleted

A webhook endpoint was deleted. The deleted endpoint does not receive this event.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "webhook.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the webhook for example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "endpoint_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "host": "example.com"
  }
}

webhook.secret_rotated

A webhook endpoint's signing secret was rotated. The secret itself is never in an event.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "webhook.secret_rotated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina rotated the signing secret of the webhook for example.com",
    "subject": {
      "ref": "",
      "name": "example.com"
    },
    "endpoint_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "host": "example.com"
  }
}

Settings events

workspace.created

A workspace was created by an Owner (in the console or with an API key).

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "workspace.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina created the workspace \"Acme Uganda\"",
    "subject": {
      "ref": "",
      "name": "Acme Uganda"
    }
  }
}

workspace.desk_activated

SautiDesk was activated for the workspace. Sent once.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "workspace.desk_activated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "system",
    "name": "SautiDesk"
  },
  "data": {
    "summary": "SautiDesk was activated for this workspace",
    "source": "first_call"
  }
}

queue.created

A queue was created.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "queue.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina created the queue \"Sales\"",
    "subject": {
      "ref": "",
      "name": "Sales"
    }
  }
}

queue.updated

A queue was edited.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "queue.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina edited the queue \"Sales\"",
    "subject": {
      "ref": "",
      "name": "Sales"
    }
  }
}

queue.members_changed

Who is in a queue changed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "queue.members_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina changed who is in the queue \"Sales\"",
    "subject": {
      "ref": "",
      "name": "Sales"
    }
  }
}

queue.deleted

A queue was deleted.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "queue.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the queue \"Sales\"",
    "subject": {
      "ref": "",
      "name": "Sales"
    }
  }
}

category.created

A ticket category was added.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "category.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the category \"Billing\"",
    "subject": {
      "ref": "",
      "name": "Billing"
    }
  }
}

category.renamed

A ticket category was renamed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "category.renamed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina renamed a category to \"Billing\"",
    "subject": {
      "ref": "",
      "name": "Billing"
    }
  }
}

category.deleted

A ticket category was deleted.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "category.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the category \"Billing\"",
    "subject": {
      "ref": "",
      "name": "Billing"
    }
  }
}

outcome.created

A call outcome was added.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "outcome.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the call outcome \"Resolved\"",
    "subject": {
      "ref": "",
      "name": "Resolved"
    }
  }
}

outcome.updated

A call outcome was edited.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "outcome.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina edited the call outcome \"Resolved\"",
    "subject": {
      "ref": "",
      "name": "Resolved"
    }
  }
}

outcome.deleted

A call outcome was deleted.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "outcome.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the call outcome \"Resolved\"",
    "subject": {
      "ref": "",
      "name": "Resolved"
    }
  }
}

ticket_outcome.created

A ticket outcome was added.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket_outcome.created",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the ticket outcome \"Fixed\"",
    "subject": {
      "ref": "",
      "name": "Fixed"
    }
  }
}

ticket_outcome.updated

A ticket outcome was edited.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket_outcome.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina edited the ticket outcome \"Fixed\"",
    "subject": {
      "ref": "",
      "name": "Fixed"
    }
  }
}

ticket_outcome.deleted

A ticket outcome was deleted.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket_outcome.deleted",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina deleted the ticket outcome \"Fixed\"",
    "subject": {
      "ref": "",
      "name": "Fixed"
    }
  }
}

ticket_outcome.reordered

The ticket outcomes were put in a new order.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "ticket_outcome.reordered",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina reordered the ticket outcomes"
  }
}

holiday.added

A holiday was added to the business hours.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "holiday.added",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the holiday \"Christmas\"",
    "subject": {
      "ref": "",
      "name": "Christmas"
    }
  }
}

holiday.updated

A holiday was edited.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "holiday.updated",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina edited a holiday"
  }
}

holiday.removed

A holiday was removed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "holiday.removed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina removed a holiday"
  }
}

holiday.seeded

The public holidays of a year were added.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "holiday.seeded",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina added the public holidays for 2026"
  }
}

agent.ring_changed

Where an agent's phone rings was changed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "agent.ring_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina set where Bruce's phone rings"
  }
}

activity_log.settings_changed

The activity log's own settings (on or off, how long it is kept) changed.

{
  "id": "8e1f0d2c-4b3a-4a59-9c68-7d5e4f3a2b1c",
  "type": "activity_log.settings_changed",
  "created_at": "2026-10-14T08:15:00Z",
  "workspace_id": "4d5e6f70-8192-4a3b-9c4d-6e7f80912a3b",
  "actor": {
    "type": "person",
    "id": "7a9e2d54-1c3b-4f60-8a7d-2e5b9c014f33",
    "name": "Amina Hassan"
  },
  "data": {
    "summary": "Amina changed the activity log settings"
  }
}

GET/v1/desk/webhooks

List webhooksdesk.admin

POST/v1/desk/webhooks

Create a webhookdesk.admin

PATCH/v1/desk/webhooks/{id}

Update a webhookdesk.admin

DELETE/v1/desk/webhooks/{id}

Delete a webhookdesk.admin

GET/v1/desk/webhooks/{id}/deliveries

List a webhook's deliveriesdesk.admin

POST/v1/desk/webhooks/{id}/deliveries/{did}/retry

Retry a deliverydesk.admin

POST/v1/desk/webhooks/{id}/rotate-secret

Rotate the signing secretdesk.admin

POST/v1/desk/webhooks/{id}/test

Send a test eventdesk.admin

GET/v1/desk/webhooks/events

List webhook event typesdesk.admin

Team and licences

Workspace members, invitations, roles and Desk licences, and creating another workspace.

GET/v1/desk/invitations

List invitationsdesk.admin

POST/v1/desk/workspaces

Create another workspacedesk.admin

POST/v1/invitations

Invite a persondesk.admin

DELETE/v1/invitations/{invitation_id}

Revoke an invitationdesk.admin

PATCH/v1/memberships/{user_id}

Change a member's role or namedesk.admin

DELETE/v1/memberships/{user_id}

Remove a memberdesk.admin

PUT/v1/memberships/{user_id}/licences

Set a member's Desk licencesdesk.admin

POST/v1/memberships/{user_id}/reactivate

Reactivate a removed memberdesk.admin

Limits and errors

Errors are JSON with an error message and a stable code. Branch on the code, not the text.

Status and code	Meaning
403 api_key.scope_denied	The key's scopes do not cover this route. The body names the scope it needs in required_scope.
403 desk.pro_required	A Supervise route on a Basic workspace. Supervise is available on SautiDesk Pro only.
403 desk.licence_required	The person lacks the licence this route needs (Converse, Contacts or Supervisor). The body lists the licences that would work.
403 desk.admin_required	The route is for workspace owners and admins only.
409 desk.agent_busy	The person is already on a live call. Each person can hold one live call at a time.
403 auth.session_required	Sign-in and PIN lock routes (/v1/desk/auth/*) work in the SautiDesk console only.
403 desk.billing_session_required	Billing, payments and buying a number (/v1/desk/billing/*, claim-number, trial keep) work in the SautiDesk console only.