All docs

API reference: Response Desk

Service levels, queues, holidays, escalation rules, availability, reports and helpdesk imports for the Response Desk.

Updated . 16 min read.

Conversations, replies and email channels live under /desk/threads and /desk/email-channels. This page covers service levels, reports and helpdesk imports. All of them need the Scale plan (a plan without Response Desk gets 403 with an upgrade payload), bearer auth, and are scoped to the token's workspace. A record from another workspace answers 404.

Base URL: https://formspring.io/api/v1

Method Path Ability
GET /desk/sla desk:read
POST /desk/sla/policies desk:admin
PUT | DELETE /desk/sla/policies/{policy} desk:admin
PUT /desk/sla/holidays desk:admin
POST /desk/sla/escalation-rules desk:admin
PUT | DELETE /desk/sla/escalation-rules/{rule} desk:admin
POST /desk/queues desk:admin
PUT | DELETE /desk/queues/{queue} desk:admin
PUT /desk/availability desk:reply
GET /desk/labels desk:read
POST /desk/labels desk:admin
PATCH | DELETE /desk/labels/{label} desk:admin
GET /desk/live desk:read
GET /desk/macros desk:read
POST /desk/macros desk:admin
PATCH | DELETE /desk/macros/{macro} desk:admin
POST /desk/threads/{thread}/macros/{macro} desk:assign and/or desk:reply
GET /desk/views desk:read
POST /desk/views desk:reply
PATCH | DELETE /desk/views/{view} desk:reply
GET /desk/threads/{thread}/followers desk:read
POST | DELETE /desk/threads/{thread}/followers desk:assign
POST /desk/threads/{thread}/merge desk:assign
GET /desk/automation-rules desk:read
POST /desk/automation-rules desk:admin
PATCH | DELETE /desk/automation-rules/{automationRule} desk:admin
GET /desk/automation-runs desk:read
GET /desk/routing-rules desk:read
POST /desk/routing-rules desk:admin
PATCH | DELETE /desk/routing-rules/{routingRule} desk:admin
GET | PUT /desk/auto-resolve desk:read | desk:admin
GET /desk/notification-preferences desk:read
PUT /desk/notification-preferences desk:reply
GET /desk/attributes desk:read
POST /desk/attributes desk:admin
PATCH | DELETE /desk/attributes/{deskAttribute} desk:admin
GET /desk/webhooks desk:read
POST /desk/webhooks desk:admin
PATCH | DELETE /desk/webhooks/{deskWebhook} desk:admin
POST /desk/webhooks/{deskWebhook}/rotate-secret desk:admin
GET /desk/webhooks/{deskWebhook}/deliveries desk:read
POST /desk/webhooks/{deskWebhook}/deliveries/{deskWebhookDelivery}/replay desk:admin
GET /desk/reports desk:read
GET /desk/reports/export desk:read
POST /desk/imports/dry-run desk:admin
POST /desk/imports desk:admin
GET /desk/imports/{run} desk:read

Writes also need the token owner to be a workspace owner or admin.

Reply to a conversation

http
POST /desk/threads/{thread}/messages
Content-Type: application/json

{ "mode": "reply", "body": "Thanks, it is fixed.", "expected_revision": 14 }

Every email reply must carry expected_revision: the revision of the conversation as you last read it (from GET /desk/threads/{thread}). The revision moves on with every new customer message, internal note, reply, assignment and status change, so a reply written against an old state is never sent blind. Changing the priority or labels does not move it.

Answer Meaning
201 Queued. The message is in the thread right away with a queued delivery state.
409 revision_conflict The conversation moved on after you read it. The body carries the latest state and recent_messages. Your text is kept as a draft. Read it, then send again with the new revision.
428 revision_required The reply had no expected_revision. Nothing is sent; your text is kept as a draft. The body carries current_revision and an upgrade block describing the field to add.

Internal notes ("mode": "note") never reach the customer and do not need a revision. The same rule applies to the dashboard, the mobile app and the MCP tool reply_desk_thread.

If you maintain an integration that replied without expected_revision, read the thread first and send its revision with each reply. A saved draft appears in the agent's composer the next time they open the conversation, marked as needing review.

Priority, labels and the list

GET /desk/threads takes q to search what was said (the subject, the customer address and the text of any message or note; every word must appear, "quoted phrases" stay together; matches carry search_snippet), priority (one of low, normal, high, urgent, or a comma-separated list), label (label ids or names, comma-separated, any of them), status, view and sort (latest, oldest, priority, longest_waiting). PATCH /desk/threads/{thread} accepts priority, label_ids (replaces the labels) and snoozed_until next to the existing fields. Each thread carries priority and labels (id, name, color).

tags still works: every tag is a label too, created with the default colour when it does not exist yet, and tags mirrors the label names. In POST /desk/threads/bulk, action can also be priority (with priority), label or unlabel (with label_ids).

http
POST /desk/labels
{ "name": "Billing", "color": "#2563EB" }

Names are unique per workspace ignoring case. DELETE /desk/labels/{label} answers 202: a background job takes the label off every conversation.

Notes, mentions and followers

A note ("mode": "note") can carry mentions, a list of teammate user ids. @Full Name, a unique @FirstName or @email written in the note counts too. Everyone mentioned is notified and follows the conversation; an id that is not a teammate who can open it answers 422. Mentions in a customer reply are ignored.

POST /desk/threads/{thread}/followers follows as you, or as the teammate in user_id; DELETE stops following (pass user_id to remove a teammate). All three follower calls answer with the current list of followers.

Attach files

POST /desk/threads/{thread}/messages also accepts multipart/form-data with up to five files[] (5 MB each; images, PDFs, Word, Excel, CSV and text). Every file is type-checked and malware-scanned; a refused file answers 422 on files and nothing is sent. Replies carry the files as email attachments.

Macros

A macro is a saved reply with an optional short code and actions.

http
POST /desk/macros
{
  "name": "Refund approved",
  "shortcode": "refund",
  "body_md": "Hi {{contact.first_name|there}}, your refund is on its way.",
  "actions": [
    { "type": "label", "value": [3] },
    { "type": "priority", "value": "low" },
    { "type": "status", "value": "resolved" },
    { "type": "reply" }
  ]
}

Action types, each at most once and run in order: assign (a user id, "me" or "unassigned"), label and unlabel (label ids), status (open, pending, resolved, spam), priority, snooze (hours), note (private note text) and reply (no value; sends body_md, and with status: resolved sends and resolves in one step). Placeholders: contact.name, contact.first_name, contact.email, agent.name, agent.first_name, agent.email, thread.subject, thread.id, team.name, with an optional fallback such as {{contact.first_name|there}}; an unknown placeholder answers 422. body_md may be empty when there are actions. Short codes are unique per workspace ignoring case. DELETE answers 202.

POST /desk/threads/{thread}/macros/{macro} runs a macro on a conversation. Its token needs desk:assign for assign, label, status, priority and snooze actions, and desk:reply for notes, the send action or a macro with text. The answer is { "body", "subject", "sent", "applied": [...], "skipped": [...], "revision" }: the text with placeholders filled in (empty when the macro sent it), what was done and what had to be skipped. Every change appears as a line in the conversation, after one that names the macro.

Saved views

GET /desk/views lists your saved list views and the ones your team shares (id, name, filters, shared, mine). POST /desk/views takes name, filters (any of view, channel, status, assignee, priority, label, sort, q, from, to) and shared. You can change or delete only your own. Open one with GET /desk/threads?saved_view={id}; any filter you pass next to it wins.

The live view

GET /desk/live returns counts (open, unattended for conversations nobody has replied to, unassigned, waiting_for_reply, overdue) and agents (id, name, available, away_until, open, active_now). Counts only cover conversations the token's owner can open.

Read the service-level setup

http
GET /desk/sla

Returns policies, holidays, escalationRules, queues, your availability and the priorities (low, normal, high, urgent).

Create an SLA policy

http
POST /desk/sla/policies
Content-Type: application/json

{
  "name": "Standard",
  "channels": ["email"],
  "first_response_minutes": 60,
  "next_response_minutes": 120,
  "resolution_minutes": 1440,
  "use_business_hours": true,
  "active": true,
  "priority_overrides": { "urgent": { "first_response_minutes": 15 } }
}

At least one of the three targets is required (1 to 43200 minutes). 201 returns the policy; 422 lists what is wrong. PUT replaces the policy; DELETE answers 204 and leaves clocks that are already running untouched.

Every conversation exposes its clocks and reopened_count on GET /desk/threads/{thread} as sla_clocks, each with kind (first, next, resolution), state (running, paused, met, met_late, breached), due_at, business_time and, while paused, a pause_reason.

Holidays

http
PUT /desk/sla/holidays
{ "country": "DE", "dates": [{ "date": "2026-12-24", "name": "Company day" }] }

Replaces the calendar. Holidays only change due times while business hours are on.

Escalation rules and queues

http
POST /desk/sla/escalation-rules
{ "name": "Warn at 80%", "trigger": "warning", "threshold_percent": 80, "clock_kinds": ["first"],
  "actions": { "notify_user_ids": [12], "set_priority": "high" }, "active": true }

POST /desk/queues
{ "name": "Billing", "strategy": "least_loaded", "max_open_per_agent": 5, "member_ids": [12, 14], "active": true }

An escalation rule needs at least one action, and every user id must belong to your workspace (otherwise 422). strategy is round_robin or least_loaded.

Automation rules

A rule runs on an event when its conditions hold, optionally after a delay, and then carries out its actions.

http
POST /desk/automation-rules
{
  "name": "Refunds are urgent",
  "event": "message_created",
  "match": "all",
  "conditions": [
    { "field": "body", "operator": "contains", "value": ["refund"] },
    { "field": "assignee", "operator": "is_not_set" }
  ],
  "actions": [
    { "type": "priority", "value": "urgent" },
    { "type": "notify", "value": { "user_ids": [12], "include_assignee": false, "message": "Refund request" } }
  ],
  "execution_delay_minutes": 15,
  "once_per_thread": true
}

event is thread_created (the first message), message_created (a message from the customer, the first included), thread_updated (status, priority, assignee, queue or labels changed) or thread_reopened. Condition field is one of channel, status, priority, label, assignee, queue (ids for the last three), subject, body, sender_email, sender_domain; operator is is, is_not, contains, not_contains, is_set or is_not_set, as allowed for the field (GET /desk/automation-rules returns the catalogue in meta.conditions). value is a list: any of these.

Action types, each at most once and run in order: assign (a user id or "unassigned"), queue (a queue id; the conversation goes to its next available agent), label and unlabel (label ids), status, priority, snooze (hours), note and reply (text; placeholders such as {{contact.first_name}} work; sent as the rule's author and marked automated), notify ({user_ids, include_assignee, message}) and webhook ({url, secret}). A webhook must be a public address; the secret is stored encrypted and never returned (has_secret tells you one is set). With a secret, each POST carries X-Formspring-Signature: t=<unix>,v1=<hmac-sha256 of "<unix>.<body>">.

An unknown field, operator, action, a person who is not in the workspace, or a webhook to a private address answers 422. What a rule changes never starts another rule, once_per_thread limits a rule to one run per conversation, and no rule runs more than five times on one conversation within ten minutes. DELETE answers 202.

http
GET /desk/automation-runs?rule_id=4&thread_id=ab12cd34ef56&limit=50

The log, newest first and kept for 30 days. Each line has status (applied, skipped, failed, scheduled for a run still waiting out its delay, or cancelled when the conversation no longer matched when the wait was over), applied, skipped and error.

Routing rules and auto-resolve

http
POST /desk/routing-rules
{
  "name": "Acme refunds",
  "strategy": "round_robin",
  "conditions": { "channels": ["email"], "match": "all", "rules": [ { "field": "sender_domain", "operator": "is", "value": ["acme.example"] } ] },
  "actions": { "member_ids": [12, 14], "max_open_per_agent": 5 }
}

strategy is round_robin, default_assignee (actions.assignee_id) or queue (actions.queue_id). conditions.rules takes the same conditions as automation rules. PATCH changes only what you send; active: false pauses a rule and priority reorders it. Rules run in priority order and the first match wins.

http
PUT /desk/auto-resolve
{ "enabled": true, "days": 14, "message": "Just write back if you still need help.", "label_id": 3, "only_when_answered": true }

Resolves conversations after that many days without activity, with an optional closing message and label. By default only conversations your team has answered are resolved.

Notification preferences

http
PUT /desk/notification-preferences
{ "events": { "assigned": { "email": false }, "mention": { "push": false } } }

The token owner's own choice of which Desk events reach them by email and by push; it never reads or changes anyone else's. Events: assigned, mention, followed_update, sla_breached and automation (the last two are email only). Only the events and channels you name change; everything is on until switched off. The response lists every event with its label, channels, email and push. See Desk notifications.

Custom attributes

http
POST /desk/attributes
{ "key": "plan", "label": "Plan", "scope": "customer", "type": "list", "options": ["Free", "Pro"] }

scope is thread (a value per conversation) or customer (a value per customer address); type is text, number, link, date, list or checkbox. key (lower case letters, digits and underscores), scope and type cannot change later. A workspace can have 30. Set values with the conversation update:

http
PATCH /desk/threads/{thread}
{ "attributes": { "plan": "Pro", "order_id": "A-100", "renews": null } }

Values are checked against the type (422 otherwise) and null clears one. Customer values need a customer email address on the conversation. GET /desk/threads/{thread} returns attributes (every definition with its value) and the list returns custom_attributes (the conversation's own values). Filter the list with ?attribute=plan:Pro. In automation and routing conditions the field is attribute:<key>, with the extra operators gt and lt for numbers and before and after for dates.

Webhooks

http
POST /desk/webhooks
{ "url": "https://example.com/hooks/desk", "label": "CRM", "events": ["thread.created", "sla.breached"] }

Events are thread.created, message.created, thread.status_changed, thread.assigned and sla.breached; leave events empty for all of them. The address must be public (private and internal hosts are refused with 422), and a workspace can have 10. The 201 response carries the signing secret once and never again.

POST /desk/webhooks/{deskWebhook}/rotate-secret with { "overlap_hours": 24 } (0 to 168) replaces the secret and returns the new one once; the old one keeps signing for the overlap. GET .../deliveries?limit=25 is the delivery log (kept for 30 days) with status (pending, delivered or failed), attempts, response_status and error. POST .../deliveries/{deskWebhookDelivery}/replay queues the same body again (202). Deleting is queued (202). Signatures and retries are described in Desk webhooks.

Merge conversations

http
POST /desk/threads/{thread}/merge
{ "into": "ab12cd34ef56" }

Moves the messages of {thread} into the conversation into in time order and returns that conversation. Both must be with the same customer (the same contact or reply address) and in the same project, otherwise 422; a live chat can be kept but not merged away. The merged conversation answers every later request with a 301 (GET) or 308 (other methods) redirect to the one you kept, and shows merged_into. It cannot be undone.

Availability

http
PUT /desk/availability
{ "available": false, "away_until": "2026-11-02T08:00:00Z" }

Changes only the token owner. An absence with away_until ends by itself.

Reports

http
GET /desk/reports?from=2026-10-01&to=2026-10-31&channel=email&agent=12&tag=billing

Returns volume, first reply and resolution times in business and calendar time, reopen counts, satisfaction (with scored, average_score and a five-entry distribution of 1 to 5 scores), and workload per agent and channel. agent is a member id or unassigned. The range is at most 366 days. GET /desk/reports/export returns the same figures as CSV.

Import a helpdesk export

http
POST /desk/imports/dry-run
Content-Type: multipart/form-data

source=helpscout
file=@conversations.json
project_id=3

source is helpscout, zendesk or freshdesk; file is JSON or CSV (Help Scout is JSON only), up to 10 MB, not zipped. The dry run writes nothing and returns the run with stats, unsupported and assignees.list; each person has a key. Confirm it:

http
POST /desk/imports
{ "preview_run": "01J...", "assignee_map": { "alex@old-company.example": 12 } }

202 returns the queued run; poll GET /desk/imports/{run} until status is completed or failed. assignee_map values must be members who can open the project (otherwise 422 and nothing is queued). Imported history keeps its original dates, never sends email or notifies anyone, and importing the same export again adds nothing twice.