Core Concepts

Outbound Campaigns

A campaign is a batch of automated outbound calls powered by an AI agent. Define a list of contacts, assign an agent, set a schedule, and start the campaign. The platform dials each contact, runs the agent conversation, and records the results.

Use campaigns for sales outreach, appointment reminders, surveys, follow-ups, collections, and any scenario where you need to call a list of people with a consistent message.

Campaign Lifecycle

A campaign moves through these statuses:

Status	Description
`draft`	Created but not yet fully configured — no call list or schedule set
`active`	Running and actively dialing contacts
`paused`	Temporarily stopped — active calls finish but no new calls are initiated
`completed`	All contacts have been processed
`failed`	An error stopped the campaign

The typical flow is: draft -> active -> completed, with optional pause/resume cycles in between.

Code
# Create campaign
POST https://api.neuratel.ai/campaigns

# Configure and start
POST https://api.neuratel.ai/campaigns/{campaign_id}/start

# Pause (active calls finish, no new calls)
POST https://api.neuratel.ai/campaigns/{campaign_id}/pause

# Resume
POST https://api.neuratel.ai/campaigns/{campaign_id}/start

# Stop permanently
POST https://api.neuratel.ai/campaigns/{campaign_id}/stop

Creating a Campaign

Via API

Code
curl -X POST https://api.neuratel.ai/campaigns \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Sales Outreach",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Follow up on Q2 inbound leads"
  }'


Code
import os, httpx

response = httpx.post(
    "https://api.neuratel.ai/v1/campaigns",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
    json={
        "name": "Q2 Sales Outreach",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "description": "Follow up on Q2 inbound leads",
    },
)
campaign = response.json()


Code
const response = await fetch("https://api.neuratel.ai/v1/campaigns", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEURATEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Q2 Sales Outreach",
    agent_id: "550e8400-e29b-41d4-a716-446655440000",
    description: "Follow up on Q2 inbound leads",
  }),
});
const campaign = await response.json();

Configure Schedule and Settings

After creation, attach a call list, schedule, and dialing configuration:

Code
curl -X PUT https://api.neuratel.ai/campaigns/{campaign_id} \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "call_list_id": "770e8400-e29b-41d4-a716-446655440002",
    "phone_number_id": "880e8400-e29b-41d4-a716-446655440003",
    "call_schedule": {
      "start_time": "09:00",
      "end_time": "17:00",
      "days_of_week": [1, 2, 3, 4, 5],
      "timezone": "America/New_York"
    },
    "campaign_config": {
      "max_concurrent_calls": 5,
      "retry_attempts": 3,
      "retry_delay_seconds": 1800,
      "call_timeout_seconds": 60
    }
  }'

Call Lists

A call list is a reusable group of contacts. Each campaign dials the contacts in its assigned list.

Create a Call List

Code
curl -X POST https://api.neuratel.ai/lists \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "January Leads", "description": "Leads from January marketing campaign"}'


Code
response = httpx.post(
    "https://api.neuratel.ai/v1/lists",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
    json={"name": "January Leads", "description": "Leads from January marketing campaign"},
)


Code
await fetch("https://api.neuratel.ai/v1/lists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEURATEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "January Leads", description: "Leads from January marketing campaign" }),
});

Add a Contact

Code
curl -X POST https://api.neuratel.ai/lists/{list_id}/contacts \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "custom_data": {
      "company": "Acme Corp",
      "lead_source": "Website"
    }
  }'

Bulk Import via CSV

Upload a CSV file with up to 10,000 contacts per import (max 10 MB file size):

Code
curl -X POST https://api.neuratel.ai/lists/{list_id}/bulk-import \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -F "[email protected]"

The CSV should include a header row. Required column: phone_number. Optional columns: first_name, last_name, email, company, subject, city, country, industry, profile, and any custom fields.

Example CSV:

Code
phone_number,first_name,last_name,company,lead_source
+14155550123,John,Doe,Acme Corp,Website
+14155550456,Jane,Smith,Widget Inc,Referral

Contacts

Each contact has a phone number and optional variables that the agent can use during the conversation.

Contact Fields

Field	Required	Description
`phone_number`	Yes	E.164 format
`first_name`	No	Contact's first name
`last_name`	No	Contact's last name
`email`	No	Email address
`company`	No	Company name
`subject`	No	Call reason or topic
`city`	No	City
`country`	No	Country
`industry`	No	Industry sector
`profile`	No	Contact notes
`custom_data`	No	JSON object with any additional fields

Contact Status

Status	Description
`active`	Available to be called
`called`	Has been called
`dnc`	Do Not Call — excluded from dialing
`invalid`	Invalid phone number — skipped

Dynamic Variables

Contact data is injected into the agent's system prompt at call time as template variables. This lets a single agent configuration handle personalized conversations for each contact.

Available template variables:

Variable	Source
`{{first_name}}`	Contact `first_name` field
`{{last_name}}`	Contact `last_name` field
`{{phone_number}}`	Contact `phone_number` field
`{{email}}`	Contact `email` field
`{{company}}`	Contact `company` field
`{{subject}}`	Contact `subject` field
`{{city}}`	Contact `city` field
`{{country}}`	Contact `country` field
`{{industry}}`	Contact `industry` field
`{{contact_data.field}}`	Any key from `custom_data`

Example Prompt Using Variables

Code
You are calling on behalf of Acme Corp. When the call connects, say:
"Hi, am I speaking with {{first_name}} {{last_name}} from {{company}}?"

If confirmed, continue with: "I am calling to follow up on your inquiry about {{subject}}."
If wrong person: "Sorry to bother you, have a great day."

Campaign Execution

When a campaign is active:

The scheduler checks whether the current time is within the configured calling hours.
The next pending contact is selected from the call list.
Concurrency limits are checked — if max_concurrent_calls is reached, the system waits.
The agent dials the contact.
The agent handles the conversation using the contact's variables.
The contact's status is updated based on the call outcome.
If the call failed and retry attempts remain, a retry is scheduled.
The system moves to the next contact.

Retry Logic

Configure how failed calls are retried:


Code
{
  "campaign_config": {
    "retry_attempts": 3,
    "retry_delay_seconds": 1800,
    "retry_on": ["no_answer", "busy", "failed"]
  }
}

After all retry attempts are exhausted, the contact is marked with its final status.

Limits

Limit	Value
Contacts per bulk CSV import	10,000
Max CSV file size	10 MB
Max concurrent calls per campaign	Depends on plan

Compliance

Do Not Call (DNC) — Scrub your contact lists against national and state DNC registries before importing. You are responsible for DNC compliance.

Calling hours — Configure calling windows in the campaign schedule to comply with local regulations (e.g., FTC rules require calls between 8 AM and 9 PM local time in the US).

Caller ID — Ensure your outbound number is properly registered and compliant with STIR/SHAKEN attestation for US calls. Neuratel handles attestation for numbers provisioned through the platform.

API Reference

Code
# Campaign CRUD
GET    https://api.neuratel.ai/campaigns
POST   https://api.neuratel.ai/campaigns
GET    https://api.neuratel.ai/campaigns/{campaign_id}
PUT    https://api.neuratel.ai/campaigns/{campaign_id}
DELETE https://api.neuratel.ai/campaigns/{campaign_id}

# Campaign lifecycle
POST   https://api.neuratel.ai/campaigns/{campaign_id}/start
POST   https://api.neuratel.ai/campaigns/{campaign_id}/pause
POST   https://api.neuratel.ai/campaigns/{campaign_id}/stop

# Call list CRUD
GET    https://api.neuratel.ai/lists
POST   https://api.neuratel.ai/lists
GET    https://api.neuratel.ai/lists/{list_id}
DELETE https://api.neuratel.ai/lists/{list_id}

# Contacts
POST   https://api.neuratel.ai/lists/{list_id}/contacts
GET    https://api.neuratel.ai/lists/{list_id}/contacts
POST   https://api.neuratel.ai/lists/{list_id}/bulk-import

Next Steps

Agents — Configure an agent for outbound conversations
Phone Numbers — Use numbers as outbound caller ID
Analytics — Track campaign performance and call outcomes

Last modified on November 7, 2026

Organizations DNC Directory