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
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).
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.
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
GET /desk/sla
Returns policies, holidays, escalationRules, queues, your availability and the priorities (low, normal, high, urgent).
Create an SLA policy
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
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
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.
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.
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
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.
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
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
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:
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
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
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
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
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
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:
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.
