Skip to main content
A play finds leads on a cadence: each run looks for accounts that show its signal, keeps the ones in its segment, finds the whoToTarget person there, and writes them a first message. The user keeps or rejects each lead; a kept lead enters the play’s sequence. Plays belong to the organization of the user who created the key, whoever created the play. Each run spends the organization’s credits.

Create and change

A draft runs nothing and costs nothing. The fields left out take their default: review before sending, a run every day at 07:00, 10 qualified leads per run, the channel’s usual steps. defaulted lists them. config and limits in a play have the shape the bodies take, so a client can send back what it read. In PATCH, a block in changes replaces the play’s: sequence and context whole, delivery field by field. A new sequence.channel without steps gets that channel’s steps, written for the play from the organization’s Brain; without a Brain the change answers 409 company_icp_brief_not_found.
Each change is a version. GET /v1/plays/{id}/versions lists them, newest first: who made it (made_by), when, and changes, each field before and after. versions/{version}/restore brings the play back to one of them: a new version with its content (its blocks and its limits; the play keeps its current name), checked as a PATCH is. The versions in between stay in the history.

Launch and follow

launch starts the play’s scheduled run with the delivery the play has. The first run comes at the next run time. schedule_id is then set. That scheduled run belongs to the member the play acts for, usually its creator: with that member’s key, GET /v1/scheduled-runs/{schedule_id}/runs lists the runs and POST /v1/scheduled-runs/{schedule_id}/run starts one now; with another member’s key they answer 404 scheduled_run_not_found. missing_accounts names the channels no connected account can send from: kept leads wait there until an account is connected in the app. delivery.mode: auto (autopilot) keeps every lead without review and sends its messages. Set it only when the user asks.

Sort the leads

Read the leads waiting for review with review_state=review. A lead kept or rejected leaves that list: after deciding some, read again from offset=0. Keeping one puts it in the sequence, which sends its first message (first_message). Rejecting one needs reasons: the next runs learn from them, and the person and their company are excluded for the whole organization. A lead already decided answers 409 play_lead_decided; one the sequence turns down answers 422 play_lead_not_enrolled with the reason in message. The right company with the wrong person: replace sets the lead aside (only the person is excluded) and starts a run of the play to find someone else there; it spends credits like any run, and needs a launched play that is not archived.

Messages and proposals

message/rewrite has a model write the lead’s first message again; PUT message saves it as written, with subject only when the sequence’s first message is an email. Once the lead is in its sequence, a message that fits that step is the one it sends (one that does not fit stays on the lead only), and a message edited by hand there answers 409 play_message_edited_by_hand unless overwrite_hand_edit is true. steps/rewrite rewrites the steps’ writing instructions for every next message. leads/move moves leads in review found for an earlier channel to the play’s channel, each with a new message. The models these calls use are debited at their cost. After its runs and the user’s verdicts, a play can propose a change to itself or to the Brain. GET /v1/plays/news lists the proposals with what else is new. apply makes a new version; a proposal made for blocks that changed since answers 409 play_update_stale, and one with no change to the play’s blocks 409 play_update_not_applicable.

Delete

DELETE /v1/plays/{id} stops the play’s runs and deletes its sequences, so nothing more is sent. Its table stays in its workspace. To keep a play, archive it instead.