Quickstart

Trigger your first AI call in three steps — an API key, a campaign, one request.

The fastest useful thing you can do with the ClearTalk API: hand it a lead, and have your AI agent call them seconds later. Three steps.

Step 1 — Create an API key

In your dashboard: Integrations → API access → Generate key. The key (starting ct_) is shown once — store it safely. Details in Authentication.

Step 2 — Find your campaign's trigger URL

Calls are triggered into a campaign — the campaign supplies the agent, the working hours, and the follow-up rules. Open any calling campaign in your dashboard and check its Trigger Instructions panel: it shows the campaign's ID, the exact URL, and a copyable example.

Campaigns wait to be triggered

Standard calling and texting campaigns don't dial through a list on their own — they act when a lead is posted to their trigger URL. An "active" campaign with no triggers arriving does nothing. (Scheduled batch campaigns are the exception.)

1
A lead appears in your system
A form fill, a new CRM record, an event in your own app.
2
You post it to the campaign
One request carrying the phone number, plus anything else the agent should know.
3
ClearTalk creates or updates the contact
Your custom fields become variables the agent can use by name.
4
The agent calls
Within the campaign's working hours, following its follow-up rules.
5
The result comes back
Through your webhook, into whichever system you pointed it at.

Your request is step 2. Without it, nothing happens.

Step 3 — Trigger a call

curl -X POST "https://backboard.cleartalk.ai/api/public/calls/trigger/YOUR_CAMPAIGN_ID" \
  -H "Authorization: Bearer ct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "first_name": "Jamie",
    "last_name": "Rivera",
    "email": "jamie@example.com",
    "tags": ["api-test"],
    "custom_fields": { "property_address": "12 Oak Lane" }
  }'

A 202 response means the call is accepted:

{
  "ok": true,
  "queued": true,
  "status": "queued",
  "requestId": "...",
  "contactId": "...",
  "campaignId": "...",
  "contactPhone": "+15551234567"
}

The contact is created (or updated) automatically, and everything in custom_fields becomes variables your agent can use in conversation. Moments later the call appears under Conversations in your dashboard, with its recording, transcript, summary, and result.

Posted after hours? The call is held, not lost

If the lead arrives outside the campaign's calling hours, the response comes back with "status": "held" and a scheduledFor timestamp — the call places itself automatically when the window opens, in the recipient's local time. Nothing for you to retry.

Variations

Text instead of call — same body, texting campaign's URL:

POST https://backboard.cleartalk.ai/api/public/sms/trigger/YOUR_CAMPAIGN_ID

The response's status tells you what happened: sent, enrolled (into the campaign's message sequence), skipped_engaged (lead is mid-conversation — not interrupted), or suppressed (opted out).

A whole list at once — up to 5,000 contacts with optional pacing between dials:

curl -X POST "https://backboard.cleartalk.ai/api/public/campaigns/trigger-batch/YOUR_CAMPAIGN_ID" \
  -H "Authorization: Bearer ct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "+15551234567", "first_name": "Jamie" },
      { "phone": "+15559876543", "first_name": "Alex" }
    ],
    "pacing_seconds": 30
  }'

Invalid rows are reported in the response's rejected array rather than failing the batch.

Common errors

Status	Meaning
`400`	Missing or invalid phone number, or the campaign is the wrong type for this endpoint.
`401`	Bad or missing API key.
`404`	Campaign not found in your organization.
`409`	The campaign is paused, completed, or archived.
`422`	The campaign has no agent assigned, or the recipient is suppressed.

Next steps

Get call results pushed back to your system the moment each call ends.
Wire it into GoHighLevel without writing code.
Browse the full API reference for every parameter and response schema.