CallCloud API

Getting started

1. An admin creates a key in Settings, Developers, API keys. It is shown once, so copy it then.
2. Check it works: GET /me returns your workspace, reps and call outcomes.
3. Feed a campaign: create a list with contacts (POST /lists), then attach it to a campaign (POST /campaigns/:id/lists). Campaigns are created and started in the app.
4. Sync results: poll GET /calls with the next_cursor from your last page.

Base URL: https://dialer.callcloud.app/api/v1

Authentication

Send your key as a bearer token on every request. Keys start with ccp_, belong to one workspace, and must stay on your server, never in a browser.

curl https://dialer.callcloud.app/api/v1/me \
  -H "Authorization: Bearer ccp_your_key"

Errors and limits

Every error has the same shape:

{ "error": { "code": "not_found", "message": "No list with id \"abc\" in this workspace." } }

Limits: 120 requests per minute per key, 1,000 contacts per request, 30 custom fields per contact.

Your workspace

The workspace this key belongs to, its active reps, and its call outcome list. A call's outcome.id is one of these ids.

{
  "workspace": { "id": "cmv...", "name": "Acme Sales" },
  "reps": [ { "id": "cmv...", "name": "Dana R.", "email": "dana@acme.com", "role": "admin" } ],
  "outcomes": [ { "id": "meeting_booked", "label": "Meeting booked", "kind": "..." } ]
}

Lists

Your lead lists, newest first. limit is 1 to 200 (default 50).

{ "lists": [ { "id": "cmv...", "name": "October webinar", "prospects": 412, "campaign_ids": ["cmv..."], "created_at": "2026-10-20T14:02:11.000Z" } ] }

Create a list, optionally with up to 1,000 contacts in the same call.

curl -X POST https://dialer.callcloud.app/api/v1/lists \
  -H "Authorization: Bearer ccp_your_key" -H "Content-Type: application/json" \
  -d '{"name":"October webinar","contacts":[{"first_name":"Dana","last_name":"Reyes","company":"Acme","phone":"+15125550134","external_id":"crm_8812"}]}'

{
  "list": { "id": "cmv...", "name": "October webinar", "created_at": "2026-10-20T14:02:11.000Z" },
  "import": { "received": 1, "created": 1, "linked_existing": 0, "dropped_no_phone": 0, "dropped_toll_free": 0, "dropped_duplicate": 0 }
}

Add contacts to a list

Add 1 to 1,000 contacts to an existing list. Safe to resend: a contact already in the list counts as a duplicate, not a second prospect. A campaign dialing this list picks the new prospects up on its next fill, running or not.

The response is { "list_id": "...", "import": { ... } } with the same import summary as above:

The contact object

Every field is optional except that a contact needs a phone number to be dialed. Prospects are matched across your workspace on their primary number.

Campaigns

Your campaigns (archived ones left out) and the lists each one dials.

{ "campaigns": [ { "id": "cmv...", "name": "Inbound leads", "status": "dialing", "list_ids": ["cmv..."], "created_at": "2026-10-01T15:20:00.000Z" } ] }

Add a list to the lists a campaign dials. It adds, never replaces, and is safe to repeat. It never starts, stops or changes dialing.

{ "campaign_id": "cmv...", "list_ids": ["cmv...", "cmv..."] }

Sync finished calls

Finished calls, oldest change first, built for syncing into a CRM. A call shows up again when its outcome or notes change after it ends, so keep polling with your last next_cursor to get only what changed.

curl "https://dialer.callcloud.app/api/v1/calls?limit=100&connected_only=true" \
  -H "Authorization: Bearer ccp_your_key"

{ "calls": [ { ...call object... } ], "next_cursor": "MTc2MDk3...", "has_more": false }

next_cursor is kept on the last page too: poll later with it and you get only newer changes. Page until has_more is false.

One call, with transcript

Returns { "call": { ... } }: the call object plus transcript.

The call object

Hot leads: call a form fill now

For warm leads that should be called the moment they arrive, like a web form fill. The contact joins the campaign, then:

• Someone is dialing that campaign and free: one rep (the one you name, else whoever has waited longest) has their ringing lines stopped, and the lead is dialed alone on their line with a Hot lead notice. Calls already in progress are never cut. Their normal dialing resumes after the call, and the lines that were stopped are called again later.
• Nobody is free: the lead goes to the front of the campaign's queue and your workspace admins get an email. It is the first call when someone presses Start.

curl -X POST https://dialer.callcloud.app/api/v1/hot-leads \
  -H "Authorization: Bearer ccp_your_key" -H "Content-Type: application/json" \
  -d '{"campaign_id":"CAMPAIGN_ID","rep_email":"dana@acme.com","contact":{"first_name":"Sam","last_name":"Lee","phone":"+15125550134","notes":"Requested a demo on the pricing page"}}'

{ "prospect_id": "cmv...", "status": "dialing", "rep": { "email": "dana@acme.com" }, "import": { ... } }

status is dialing (with the rep) or queued. A Do Not Call person answers 409 do_not_call. Calling hours still apply: outside them the lead is queued.

Search calls

The call log with filters, newest first, with the AI summary and rep notes on each. Use it to answer questions; use GET /calls to sync everything into a CRM.

Stats

Dials, pickups, connects, conversations, meetings and talk time for a date range, broken down by rep, campaign, day, call result and outcome. Same definitions as the Analytics page.

curl "https://dialer.callcloud.app/api/v1/stats?period=30d&rep=dana@acme.com" \
  -H "Authorization: Bearer ccp_your_key"

Prospects

Search prospects, most recently contacted first.

One prospect: details, notes, imported fields, LinkedIn, and their last 20 calls with summaries.

Sequences

Available when Sequences is on for your workspace; otherwise these answer 403 not_enabled.

Your email sequences: id, on or off, sending inboxes and window, each step (number, type, delay, subject), and how many people are in each status. Add ?include_archived=true for archived ones.

Upload an attachment, for example a custom brochure, for emails you push. Send the bytes as content_base64 or give an https url to fetch it from; up to 10 MB. Returns a file_id.

Push each person's own email, with attachments, into a sequence. Each person is matched to a prospect (by prospect_id, else email) or created, added to the sequence, and their email replaces that step's template copy for them only. Sending follows the sequence: its inboxes, window, pacing and stop-on-reply. Pushing again before the step runs replaces their email. Up to 50 people per call.

curl -X POST https://dialer.callcloud.app/api/v1/sequences/SEQUENCE_ID/emails \
  -H "Authorization: Bearer ccp_your_key" -H "Content-Type: application/json" \
  -d '{"people":[{"email":"dana@acme.com","first_name":"Dana","subject":"Your custom plan","body":"Hi {{first_name}}, the plan we discussed is attached.","file_ids":["FILE_ID"]}]}'