Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Upsert the contact in your workspace (matched by primary email, falling back to phone).
  2. Append the notes you send (Speaks Spanish. Located in Madrid.) to the contact’s record so they survive across calls.
  3. 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.
  4. 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

​
method
POST
POST /api/v1/sequences/start

​
Request body

​
template_id
string
required
ID of a sequence template in your workspace. The template defines the goal prompt, allowed channels, pacing, and (optionally) the bot identity.
​
bot_id
string
Required only if the template has no bot_id. The bot whose email/phone identity will be used as the sender.
​
contact
object
required
The contact to upsert.At least one of emails or phone_numbers is required.
​
auto_approve
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.
​
idempotency_key
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.
​
name
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

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

​
Get enrollment status

​
method
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

StatusMeaning
generatingLLM is still producing the sequence. Typical 30–90s.
pending_approvalSequence is generated but awaiting human approval (only when auto_approve: false). Admins have been emailed.
approvedSteps are scheduled. The first step is in flight or already sent.
runningSequence is active across multiple steps.
stopped_replyContact replied; the sequence halted (if stop_on_reply is on for the template).
stopped_unsubscribedContact’s email/phone is suppressed.
stopped_userManually halted by a workspace user.
completedAll steps sent.
failedGeneration 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.