API reference

API: Desktop

Method	Path	What it does	Scope
GET	`/v1/desk/items`	The queue: conversations the AI handed to people (calls, website chats, text threads, escalated emails), offered to you first, then waiting, then with others. Only what you may see in each channel	`calls:read`
GET	`/v1/desk/items/:id`	One conversation: why the AI handed it off, what it collected, its summary, the conversation so far, the 360° panel (contact, account, deals, history across channels, consent and do-not-contact) and a suggested next action with its sources	`messages:read`
POST	`/v1/desk/items/:id/accept`	Take the conversation (a chat or text thread: the AI stops answering it; an email: it's assigned to you). A call is taken on your phone (web app only)	`calls:write`
POST	`/v1/desk/items/:id/hand-back`	Give the conversation back to the AI agent (a chat's visitor is told; a call gets a new voice session, which says the disclosure first) (web app only)	`messages:send`
POST	`/v1/desk/items/:id/pass`	Pass on what's offered to you: it goes to the next available person (web app only)	`calls:write`
POST	`/v1/desk/items/:id/transfer`	Hand the conversation to a teammate with a note. A call rings their own confirmed phone with the context and moves on 1; you stay on until they take it (web app only)	`messages:send`
GET	`/v1/desk/people`	Everyone's presence and how many conversations they have (for handing one on)	`calls:read`
PUT	`/v1/desk/presence`	Your presence: available (conversations are offered to you, up to your capacity), busy or away (nothing is offered, and transfers skip you)	`calls:write`
GET	`/v1/desk/settings`	Desktop settings: the SLA per channel, how long an offer to one person stands, sales-floor wins in Slack, owners' live listen and the monitoring notice	`calls:read`
PUT	`/v1/desk/settings`	Change the desktop settings (owner) (web app only)	`settings:write`

Examples

GET /v1/desk/items

The queue: conversations the AI handed to people (calls, website chats, text threads, escalated emails), offered to you first, then waiting, then with others. Only what you may see in each channel

curl -s "https://api.closefinch.com/v1/desk/items" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/desk/items`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

GET /v1/desk/items/$ID

One conversation: why the AI handed it off, what it collected, its summary, the conversation so far, the 360° panel (contact, account, deals, history across channels, consent and do-not-contact) and a suggested next action with its sources

curl -s "https://api.closefinch.com/v1/desk/items/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/desk/items/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

GET /v1/desk/people

Everyone's presence and how many conversations they have (for handing one on)

curl -s "https://api.closefinch.com/v1/desk/people" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/desk/people`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

PUT /v1/desk/presence

Your presence: available (conversations are offered to you, up to your capacity), busy or away (nothing is offered, and transfers skip you)

curl -s -X PUT "https://api.closefinch.com/v1/desk/presence" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/desk/presence`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

GET /v1/desk/settings

Desktop settings: the SLA per channel, how long an offer to one person stands, sales-floor wins in Slack, owners' live listen and the monitoring notice

curl -s "https://api.closefinch.com/v1/desk/settings" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/desk/settings`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

Request and response schemas: https://www.closefinch.com/openapi.json. All resources: API reference.