REST API endpoints for campaigns

Campaigns let you run batch outbound calling to a list of contacts using a configured AI assistant. You create a campaign with scheduling and dialing settings, add contacts to it, then start it to begin placing calls. The API gives you full control over every step of this process, from initial creation through execution.

List campaigns

GET /api/crm/campaigns Returns a paginated list of campaigns for a team. You can filter by status, assistant, and whether to include soft-deleted campaigns.

Query parameters

teamId

string

required

The team ID to list campaigns for.

status

string

Filter campaigns by status. One of: draft, scheduled, running, paused, completed, cancelled.

assistantId

string

Filter campaigns assigned to a specific assistant ID.

deleted

string

Controls whether to include soft-deleted campaigns. One of: exclude (default), include, only.

limit

integer

Maximum number of records to return. Defaults to 50.

offset

integer

Number of records to skip for pagination. Defaults to 0.

Example request

curl "https://<your-domain>/api/crm/campaigns?teamId=team_01j...&status=running&limit=20" \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "campaigns": [
    {
      "id": "camp_01j...",
      "team_id": "team_01j...",
      "assistant_id": "asst_01j...",
      "company_id": "comp_01j...",
      "name": "Q1 Outreach",
      "description": "Qualify leads from the January trade show",
      "from_number": "+12025551234",
      "status": "running",
      "call_window_start": "09:00",
      "call_window_end": "17:00",
      "call_window_timezone": "America/New_York",
      "max_concurrent_calls": 5,
      "total_contacts": 200,
      "contacts_called": 80,
      "contacts_completed": 65,
      "contacts_answered": 55,
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T14:30:00Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

campaigns

array

Array of campaign objects.

campaigns[].id

string

Unique campaign identifier.

campaigns[].team_id

string

The team this campaign belongs to.

campaigns[].assistant_id

string

The assistant assigned to place calls in this campaign.

campaigns[].company_id

string

The company associated with this campaign.

campaigns[].name

string

Campaign name.

campaigns[].status

string

Current campaign status: draft, scheduled, running, paused, completed, or cancelled.

campaigns[].from_number

string

The phone number used as the caller ID for outbound calls.

campaigns[].call_window_start

string

Start of the daily call window in HH:MM format.

campaigns[].call_window_end

string

End of the daily call window in HH:MM format.

campaigns[].call_window_timezone

string

IANA timezone for the call window (for example, America/New_York).

campaigns[].max_concurrent_calls

integer

Maximum number of calls placed simultaneously.

campaigns[].total_contacts

integer

Total number of contacts in the campaign.

campaigns[].contacts_called

integer

Number of contacts where a call attempt was made.

campaigns[].contacts_completed

integer

Number of contacts where the call reached a terminal state.

campaigns[].contacts_answered

integer

Number of contacts who answered the call.

count

integer

Total number of campaigns matching the filters (before pagination).

limit

integer

The limit value applied to this response.

offset

integer

The offset value applied to this response.

Create a campaign

POST /api/crm/campaigns Creates a new outbound calling campaign. The campaign starts in draft status. Add contacts and then call the run endpoint to begin dialing.

Request body

teamId

string

required

The team ID that owns this campaign.

assistantId

string

required

The ID of the assistant that will place calls.

companyId

string

required

The company ID to associate with this campaign.

fromNumberIds

array

required

An array of phone number IDs to use as caller IDs. Talkturo rotates across these numbers when placing calls.

name

string

required

A human-readable name for the campaign.

description

string

Optional description of the campaign’s purpose.

scheduledStartAt

string

ISO 8601 datetime for when the campaign should start automatically. If omitted, you start the campaign manually via the run endpoint.

callWindowStart

string

Start of the daily calling window in HH:MM format (for example, "09:00"). Calls only go out during this window.

callWindowEnd

string

End of the daily calling window in HH:MM format (for example, "17:00").

callWindowTimezone

string

IANA timezone for the call window (for example, "America/New_York").

maxConcurrentCalls

integer

Maximum number of simultaneous outbound calls. Defaults to 3.

maxAttemptsPerContact

integer

How many times to retry a contact who does not answer. Defaults to 3.

retryDelayMinutes

integer

Minutes to wait before retrying a contact. Defaults to 60.

settings

object

Additional campaign settings as a freeform object.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team_01j...",
    "assistantId": "asst_01j...",
    "companyId": "comp_01j...",
    "fromNumberIds": ["pn_01j..."],
    "name": "Q1 Trade Show Follow-Up",
    "description": "Follow up with leads from the January trade show",
    "callWindowStart": "09:00",
    "callWindowEnd": "17:00",
    "callWindowTimezone": "America/New_York",
    "maxConcurrentCalls": 5,
    "maxAttemptsPerContact": 3,
    "retryDelayMinutes": 60
  }'

Response

{
  "success": true,
  "campaign": {
    "id": "camp_01j...",
    "team_id": "team_01j...",
    "assistant_id": "asst_01j...",
    "company_id": "comp_01j...",
    "name": "Q1 Trade Show Follow-Up",
    "status": "draft",
    "call_window_start": "09:00",
    "call_window_end": "17:00",
    "call_window_timezone": "America/New_York",
    "max_concurrent_calls": 5,
    "total_contacts": 0,
    "contacts_called": 0,
    "contacts_completed": 0,
    "contacts_answered": 0,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Add contacts to a campaign

POST /api/crm/campaigns/{id}/contacts Adds one or more existing contacts to a campaign. Contacts must already exist in your CRM. Use the contacts endpoints to create them first if needed.

Path parameters

string

required

The campaign ID to add contacts to.

Request body

contactIds

array

required

An array of contact ID strings to add to the campaign.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns/camp_01j.../contacts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cont_01j...", "cont_02k...", "cont_03l..."]
  }'

Response

{
  "success": true
}

Start a campaign

POST /api/crm/campaigns/{id}/run Initiates outbound calls for a campaign. Talkturo dials all contacts in pending or queued status, up to the campaign’s maxConcurrentCalls limit. Use dryRun: true to preview which calls would be placed without actually dialing.

Path parameters

string

required

The campaign ID to start.

Request body

accountSlug

string

Your account slug.

maxCalls

integer

Cap the number of calls started in this execution. Useful for gradual rollouts.

dryRun

boolean

When true, the API returns which calls would be started without actually placing them. Use this to verify campaign configuration before going live.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns/camp_01j.../run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "maxCalls": 20
  }'

Response

{
  "success": true,
  "started": 18,
  "failed": 2,
  "calls": [...],
  "errors": [
    "Contact cont_09x... has no phone number",
    "Contact cont_10y... is marked do-not-call"
  ],
  "message": "Started 18 calls",
  "dryRun": false
}

started

integer

Number of calls successfully initiated.

failed

integer

Number of contacts that could not be called in this run.

calls

array

Array of call objects for the calls that were started.

errors

array

Array of error message strings describing why individual contacts were skipped.

message

string

Human-readable summary of the run.

dryRun

boolean

Reflects the dryRun value from your request.

Campaign status lifecycle

Status	Description
`draft`	Campaign created but not yet started
`scheduled`	Campaign set to start at a future `scheduledStartAt` time
`running`	Calls are actively being placed
`paused`	Campaign temporarily stopped; can be resumed
`completed`	All contacts have been reached or exhausted
`cancelled`	Campaign stopped permanently

Overview

Endpoints

Webhooks

REST API endpoints for campaigns

List campaigns

Query parameters

Example request

Response

Create a campaign

Request body

Example request

Response

Add contacts to a campaign

Path parameters

Request body

Example request

Response

Start a campaign

Path parameters

Request body

Example request

Response

Campaign status lifecycle

Overview

Endpoints

Webhooks

Documentation Index

​List campaigns

​Query parameters

​Example request

​Response

​Create a campaign

​Request body

​Example request

​Response

​Add contacts to a campaign

​Path parameters

​Request body

​Example request

​Response

​Start a campaign

​Path parameters

​Request body

​Example request

​Response

​Campaign status lifecycle

List campaigns

Query parameters

Example request

Response

Create a campaign

Request body

Example request

Response

Add contacts to a campaign

Path parameters

Request body

Example request

Response

Start a campaign

Path parameters

Request body

Example request

Response

Campaign status lifecycle