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

string

required

The team ID to list campaigns for.

string

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

string

Filter campaigns assigned to a specific assistant ID.

string

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

integer

Maximum number of records to return. Defaults to 50.

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
}

array

Array of campaign objects.

string

Unique campaign identifier.

string

The team this campaign belongs to.

string

The assistant assigned to place calls in this campaign.

string

The company associated with this campaign.

string

Campaign name.

string

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

string

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

string

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

string

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

string

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

integer

Maximum number of calls placed simultaneously.

integer

Total number of contacts in the campaign.

integer

Number of contacts where a call attempt was made.

integer

Number of contacts where the call reached a terminal state.

integer

Number of contacts who answered the call.

integer

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

integer

The limit value applied to this response.

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

string

required

The team ID that owns this campaign.

string

required

The ID of the assistant that will place calls.

string

required

The company ID to associate with this campaign.

array

required

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

string

required

A human-readable name for the campaign.

string

Optional description of the campaign’s purpose.

string

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

string

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

string

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

string

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

integer

Maximum number of simultaneous outbound calls. Defaults to 3.

integer

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

integer

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

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

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

string

Your account slug.

integer

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

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
}

integer

Number of calls successfully initiated.

integer

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

array

Array of call objects for the calls that were started.

array

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

string

Human-readable summary of the run.

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

​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