Put one planned outreach touch (an email, LinkedIn or call step for one contact) on a rep's desk with its why, facts and draft. The rep edits and sends it, or, for a started sequence on an Autopilot lane, the desk sends it at its time once the account check passes. Only an org admin (Admin or Owner) may name another rep in owner_id: an admin's personal key or OAuth connection, an org key an admin created, or an org key with no recorded creator. Any other key may name only its own person and gets 403 owner_not_self for anyone else. Posting the same external_key again updates the open card instead of adding a second one, and the new body replaces the card's context and draft rather than merging, so send the complete context every time. Needs deals:write and a key allowed to see the contact
POST /desk/cards
Put one planned touch on a rep’s desk, with its why, facts, fields and draft.
201 when the card is made. The same touch posted again (same
external_key, else the same list_id + contact_id + touch, else the
same rep, contact, channel and due day) while the card is unsent answers
200 with the same card_id and updated: true. An external_key is
kept apart per origin.kind, so two integrations may both use “1”; a
body with no origin.kind shares one namespace with every other such
caller in the org, so its key must be unique across the org. Once the rep has sent or
decided it, a re-post makes a new card, except for a sequence touch: a
sequence touch that was sent (or is sending) or that the rep skipped or
dismissed is 409 already_done with its card_id, so a retry never sends
twice. A sequence card that only expired, or a discarded sequence, can be
posted again. When the rep edited the open card’s copy, a re-post by the
same contact and channel keeps the rep’s draft and answers copy_kept: true.
A re-post REPLACES the card’s context and draft, it does not merge. The
card’s channel, persona, facts, fields, draft, sender.mailbox and origin
are dropped and the new body’s are written, and its summary line is
rebuilt, so a fact, field, persona or draft left out of the re-post is gone
from the card. Send the complete context every time. Priority comes from
the new body, so a re-post with no priority sets it back to normal.
A re-post can also MOVE the open card. It is found by its key across the
whole org, so an org admin’s key naming another rep in owner_id moves it
onto that rep’s desk (any other key gets 403 owner_not_self instead,
also when the open card sits on another rep’s desk and the key names its
own person), and the same external_key with a new contact_id
rewrites it onto that contact.
Kept from the open card: its status (a snoozed card stays snoozed), its
created and resolved times, the why when the re-post sends no
context.why, the due date when it sends no due_at, who first planned
it, and anything outside the replaced set that the re-post leaves out,
such as list_id, touch, the company when the new contact has none,
and any brief the desk wrote.
A card the desk will not make is a
4xx whose detail.reason says why.
WHO MAY NAME ANOTHER REP. Only an org admin (Admin or Owner) may put a
card on another rep’s desk: an admin’s personal key or OAuth connection,
an org key whose creator is an admin now, or an org key with no recorded
creator (it acts as the org Owner). Every other key (a member’s personal
key, an org key a member created, an agency or ops key) may name only its
own person, its holder or its creator, and gets 403 owner_not_self for
anyone else. Naming yourself always works. An admin creates an org key in
Settings, Developers, API and webhooks (Create API key), or with
POST /api-keys from their own key holding account:write; give it the
deals:write scope.
The key must be allowed to see the contact (and the account when one is
named, else the contact’s own company), checked the way the contacts and deals routes check a record id
from a body; one it may not see is 403 contact_not_allowed /
account_not_allowed and no card is made.
Authorizations
Parameters
Header Parameters
Request Body required
object
Email, linkedin or call.
The contact the touch is for.
Shaped by the channel. email: subject, body. linkedin: kind (connect or message), message, a connect note at most 300 characters. call: talking_points, questions, handoff_line.
Whose desk: a team member’s email, id or user id. Only an org admin (Admin or Owner) may name another rep: an admin’s personal key or OAuth connection, an org key an admin created, or an org key with no recorded creator. Any other key may name only its own person (a personal key’s holder, an org key’s creator); anyone else is 403 owner_not_self.
Low, normal, high or urgent.
Responses
201
Successful Response
object
object
True when the rep had edited this card’s copy on the desk: the re-post updated the card’s context but the rep’s draft was kept.
True when this body updated a card already on the desk.
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error