Sequences

Plan availability: Standard or higher (requires both Sequences and API Access). See Plans & Billing.

The Sequences API lets you trigger a fully personalized outbound campaign for a single contact from your own backend. In one call, Clarky will:

Upsert the contact in your workspace (matched by primary email, falling back to phone).
Append the notes you send (Speaks Spanish. Located in Madrid.) to the contact’s record so they survive across calls.
Generate a bespoke sequence from a saved template using a two-stage LLM pipeline — emails are written for the specific recipient, in their language, referencing real context. SMS / voice scripts are generated the same way.
Optionally launch immediately — with auto_approve: true, the first step (call or email) fires within seconds of generation completing, no human review required.

Templates encode which channels are allowed (email, voice, sms), so the API itself does not expose a channel selector — pick a template that uses the channels you want.

Generation takes time. The endpoint responds with 202 Accepted after a few hundred milliseconds, but the LLM pipeline runs in the background and takes ~30–90s before the first outbound action goes out. Poll the status endpoint to know when it has shipped.

Start a sequence

POST

POST /api/v1/sequences/start

Request body

string

required

ID of a sequence template in your workspace. The template defines the goal prompt, allowed channels, pacing, and (optionally) the bot identity.

string

Required only if the template has no bot_id. The bot whose email/phone identity will be used as the sender.

object

required

The contact to upsert.

Show Properties

string[]

Array of email addresses. The first is treated as primary and used for matching.

string[]

Array of phone numbers in E.164 format. The first is primary. Used for matching when no email is provided.

string

Free-text context the LLM will use to personalize the outreach — e.g. "Speaks Spanish. Located in Madrid. Returning lead.". On an existing contact, new notes are appended (not overwritten) with a timestamp tag like [via API 2026-05-06].

object

Workspace-defined custom fields, stored as JSON.

string[]

string

At least one of emails or phone_numbers is required.

boolean

default:"false"

When true, skips the human review gate. After generation, step 1’s scheduled_for is forced to now and the dispatcher fires immediately — the contact’s phone rings (or inbox dings) within seconds. Use this for trusted automation.When false (the default), the sequence is generated and parked in pending_approval. Workspace admins receive an email with a review link.

string

A stable identifier (e.g. your internal lead ID). Calling the endpoint a second time with the same key returns the original sequence_id and enrollment_id — no duplicate sequence is created.

string

Display name for the sequence. Defaults to the template’s name.

Response — 202 Accepted

{
  "data": {
    "sequence_id":    "seq_01HXYZ...",
    "enrollment_id":  "enr_01HXYZ...",
    "contact_id":     "c_01HXYZ...",
    "contact_action": "created",
    "auto_approve":   true,
    "status":         "generating",
    "status_url":     "/api/v1/sequences/enrollments/enr_01HXYZ..."
  }
}

Example — call back a Spanish-speaking lead immediately

curl -X POST "https://clarky.ai/api/v1/sequences/start" \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id":     "tpl_01HABC...",
    "contact": {
      "first_name":    "Maria",
      "last_name":     "García",
      "emails":        ["maria@example.com"],
      "phone_numbers": ["+34911234567"],
      "company":       "Acme Spain",
      "notes":         "Speaks Spanish. Located in Madrid. Submitted contact form 30 seconds ago asking about pricing."
    },
    "auto_approve":    true,
    "idempotency_key": "lead_20260506_84211"
  }'

Errors

Code	Meaning
`400`	Missing required field, or template has no `bot_id` and none was provided.
`401`	Invalid or revoked API key.
`403`	API key does not have `write` scope.
`404`	Template not found in this workspace.
`422`	Validation error — e.g. contact has no email or phone, or `bot_id` is from a different workspace.
`429`	Rate limit exceeded.

Get enrollment status

GET

GET /api/v1/sequences/enrollments/{enrollment_id}

Use this to poll for generation progress, see the generated steps, and check delivery state.

Status values

Status	Meaning
`generating`	LLM is still producing the sequence. Typical 30–90s.
`pending_approval`	Sequence is generated but awaiting human approval (only when `auto_approve: false`). Admins have been emailed.
`approved`	Steps are scheduled. The first step is in flight or already sent.
`running`	Sequence is active across multiple steps.
`stopped_reply`	Contact replied; the sequence halted (if `stop_on_reply` is on for the template).
`stopped_unsubscribed`	Contact’s email/phone is suppressed.
`stopped_user`	Manually halted by a workspace user.
`completed`	All steps sent.
`failed`	Generation or dispatch failed. See `generation_error`.

Example response

{
  "data": {
    "id":           "enr_01HXYZ...",
    "sequence_id":  "seq_01HXYZ...",
    "contact_id":   "c_01HXYZ...",
    "status":       "approved",
    "generation_error": null,
    "approved_at":  "2026-05-06T14:22:11Z",
    "stop_reason":  null,
    "created_at":   "2026-05-06T14:21:14Z",
    "updated_at":   "2026-05-06T14:22:11Z",
    "sequence": {
      "id":          "seq_01HXYZ...",
      "name":        "Inbound lead — Spanish",
      "status":      "active",
      "bot_id":      "b_01HDEF...",
      "template_id": "tpl_01HABC..."
    },
    "steps": [
      {
        "id":            "stp_01...",
        "sort_order":    1,
        "channel":       "voice",
        "status":        "sent",
        "scheduled_for": "2026-05-06T14:22:11Z",
        "sent_at":       "2026-05-06T14:22:18Z",
        "to_identifier": "+34911234567",
        "voice_objective": "Confirm pricing tier and book a 15-minute demo this week",
        "voice_script":    "Hola Maria, te llamo desde Acme..."
      },
      {
        "id":            "stp_02...",
        "sort_order":    2,
        "channel":       "email",
        "status":        "scheduled",
        "scheduled_for": "2026-05-07T15:00:00Z",
        "email_subject": "Resumen de la llamada y próximos pasos"
      }
    ]
  }
}

Notes & limits

Latency floor: ~30–90s from API call to first outbound action. Two LLM calls run in the background; this can’t be made faster while still producing language-matched, personalized content.
Channels are template-driven. If the template’s allowed_channels is ["email", "voice"], no SMS will be sent regardless of what the contact has on file.
Concurrent enrollments are allowed — calling the endpoint while the contact is in another active sequence will not be rejected.
Suppressed contacts (unsubscribed email, opted-out phone) cause the enrollment to fail with no_usable_channels. Polling the status endpoint will reflect this.

Getting Started

Resources

Start a sequence

Request body

Response — 202 Accepted

Example — call back a Spanish-speaking lead immediately

Errors

Get enrollment status

Status values

Example response

Notes & limits

​Start a sequence

​Request body

​Response — 202 Accepted

​Example — call back a Spanish-speaking lead immediately

​Errors

​Get enrollment status

​Status values

​Example response

​Notes & limits

Start a sequence

Request body

Response — 202 Accepted

Example — call back a Spanish-speaking lead immediately

Errors

Get enrollment status

Status values

Example response

Notes & limits