Skip to main content
POST

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Path Parameters

id
string
required

The agent's id (ag_…).

kind
enum<string>
required

The connection: calcom (calendar), grist or googlesheets (spreadsheets), zoho or zoho_bigin (CRMs), records (kept here), zendesk or salesforce (helpdesks).

Available options:
calcom,
grist,
googlesheets,
zoho,
zoho_bigin,
records,
zendesk,
salesforce

Body

application/json

The body depends on {kind}. googlesheets, zoho and zoho_bigin take no body here: they sign in through a browser in the console, and this answers 409.

apiKey
string
required

A live Cal.com API key (cal_live_…), from Settings → Developer → API keys. Write-only.

Response

Connected. inbound (helpdesks) and link.passcode (a new records link) appear only here.

One account an agent can work in. Fields beyond the first few depend on the kind: a calendar has timezone; spreadsheets and CRMs have target, match and variableColumns; records has fields, recordCount and link; a helpdesk has only account and enabled. Credentials never appear.

kind
enum<string>
required

The connection.

Available options:
calcom,
grist,
googlesheets,
zoho,
zoho_bigin,
records,
zendesk,
salesforce
name
string
required

Its display name.

signIn
enum<string>
required

How it is connected: key by POST with a key; browser through a consent screen in the console (the API cannot); none for records, which need no account.

Available options:
key,
browser,
none
available
boolean
required

Whether this deployment offers it at all.

connected
boolean
required

Whether it is connected.

account
object | null
required

Who it is connected as: { email, name }, or { host, email } for a helpdesk.

lastError
string | null
required

Why the last attempt to use it failed.

toolsInUse
integer
required

Connection tools switched on, across every connection.

maxTools
integer
required

The shared budget.

message
string
required

What happened.

signInPending
boolean

Browser sign-ins only: a sign-in was started in the console and not finished.

timezone
string | null

Calendar only: the account's timezone.

mode
enum<string>

All but the calendar and helpdesks: tool saves during the conversation; parser reads the conversation afterwards.

Available options:
tool,
parser
runAsync
boolean

Grist only: answer before the save finishes.

target
object

Spreadsheets and CRMs: what it is pinned to, and that target's real columns. Grist { doc, table, columns }; Google Sheets { spreadsheet, sheet, columns }; Zoho { module, columns }.

match
object | null

Spreadsheets and CRMs: the column that finds a lead's existing row, or null to add a row per conversation.

variableColumns
object

Spreadsheets and CRMs: column to campaign variable.

tools
object[]

Its tools. Helpdesks have none here.

fields
object[]

Records only: what is collected.

recordCount
integer

Records only: how many records have been collected.

Records only: the link to read them. The passcode is shown only by the call that makes a link.

enabled
boolean

Helpdesks only: whether it is in use.

inbound
object

Helpdesks only, and only in this response: paste both into the helpdesk's webhook so replies reach the agent.