Campaigns

Endpointhttps://api.neuratel.ai

Outbound calling campaigns — create, start, pause, and stop.

Variable Coverage For An Agent + Call List Pair

GET

https://api.neuratel.ai

/v1/campaigns/coverage

For each {{contact_variable}} referenced in the agent's prompt, report the fill rate across the call list's active contacts. Used pre-creation by the wizard so the user sees coverage before saving the campaign. Mirrors the math the /start endpoint uses to refuse launches with 0% coverage on any required var.

Variable Coverage For An Agent + Call List Pair › query Parameters

agent_id

string · uuid · required

Agent whose prompt to inspect.

call_list_id

string · uuid · required

Call list to scan for var coverage.

Variable Coverage For An Agent + Call List Pair › Responses

Successful Response

Per-required-variable fill rate across a call list's active contacts. Powers the wizard Step 1 coverage report and mirrors the math the /start hard-block uses. ``blocking_zero_pct`` is the slice that would refuse a launch.

required_variables

string[] · required

total_contacts

integer · required

object · required

blocking_zero_pct

string[] · required

List Campaigns

GET

https://api.neuratel.ai

/v1/campaigns

List outbound campaigns for your organization.

List Campaigns › query Parameters

skip

integer · min: 0

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

Default: 0

limit

integer · min: 1 · max: 100

Maximum number of records to return. Defaults to 50. Max 100.

Default: 50

status

Filter by campaign status (draft, scheduled, active, paused, stopped, completed, cancelled, error).

q

Case-insensitive substring match on campaign name.

List Campaigns › Responses

Successful Response

Paginated list of campaigns. Standardized pagination format: - results: List of campaigns - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

GET/v1/campaigns

curl --request GET \
  --url https://api.neuratel.ai/v1/campaigns

shell

Example Responses

{
  "results": [
    {
      "actual_start": "2024-01-15T09:00:15Z",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T08:00:00Z",
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "last_progress_at": "2024-01-15T12:30:00Z",
      "name": "Q1 Sales Campaign",
      "organization_id": "660e8400-e29b-41d4-a716-446655440001",
      "phone_number_id": "770e8400-e29b-41d4-a716-446655440002",
      "scheduled_start": "2024-01-15T09:00:00Z",
      "status": "active",
      "updated_at": "2024-01-15T12:30:00Z"
    }
  ],
  "metadata": {
    "count": 100,
    "has_more": true,
    "limit": 100,
    "skip": 0,
    "total": 250
  }
}

json

application/json

Create Campaign

POST

https://api.neuratel.ai

/v1/campaigns

Create a new outbound calling campaign.

Create Campaign › Request Body

Create an outbound campaign. Organization is determined from your API key - no need to specify.

name

string · required

Campaign name

agent_id

string · uuid · required

Agent ID to use for making calls

phone_number_id

string · uuid · required

Phone number ID for caller ID

Call list ID for contacts to call

Campaign description

URL to POST when campaign completes or stops. Receives JSON payload with campaign stats.

object

Call scheduling configuration

object

Campaign configuration

Create Campaign › Responses

Successful Response

Schema for outbound campaign responses. Phase 1 dropped the dead `calls_made/completed/successful` denormalized counters from the model. Aggregated stats are exposed via GET /v1/campaigns/{id}/stats (CampaignStats below) which sources from campaign_attempts.

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

POST/v1/campaigns

curl --request POST \
  --url https://api.neuratel.ai/v1/campaigns \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "phone_number_id": "00000000-0000-0000-0000-000000000000",
  "call_list_id": "00000000-0000-0000-0000-000000000000",
  "description": "string",
  "status_webhook": "string",
  "call_schedule": {
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "start_hour": 0,
    "end_hour": 0,
    "days_of_week": [
      0
    ]
  },
  "campaign_config": {
    "call_timeout_seconds": 0,
    "retry_attempts": 0,
    "retry_delay_seconds": 0,
    "retry_outcomes": [
      "string"
    ]
  }
}
'

shell

Example Request Body

{
  "name": "name",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "phone_number_id": "00000000-0000-0000-0000-000000000000",
  "call_list_id": "00000000-0000-0000-0000-000000000000",
  "description": "string",
  "status_webhook": "string",
  "call_schedule": {
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "start_hour": 0,
    "end_hour": 0,
    "days_of_week": [
      0
    ]
  },
  "campaign_config": {
    "call_timeout_seconds": 0,
    "retry_attempts": 0,
    "retry_delay_seconds": 0,
    "retry_outcomes": [
      "string"
    ]
  }
}

json

Example Responses

No example specified for this content type

application/json

Get Campaign

GET

https://api.neuratel.ai

/v1/campaigns/{campaign_id}

Retrieve a specific campaign by ID.

Get Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Get Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Update Campaign

PUT

https://api.neuratel.ai

/v1/campaigns/{campaign_id}

Update a campaign's configuration.

Update Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Update Campaign › Request Body

Schema for updating outbound campaigns. Phase 3 removed the `status` field from this schema. State changes happen ONLY through the dedicated lifecycle endpoints (/start, /pause, /resume, /stop, /cancel) which funnel through the state machine in `app/domains/campaigns/state.py`. PUT /campaigns/{id} is for editing config (name, schedule, pacing, etc.) only.

Campaign name

Campaign description

URL to POST on campaign completion/stop

Agent ID for the campaign

Phone number ID for caller ID

Call list ID for contacts to call

Call scheduling configuration

Campaign configuration

Update Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

PUT/v1/campaigns/{campaign_id}

curl --request PUT \
  --url https://api.neuratel.ai/v1/campaigns/:campaign_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "description": "string",
  "status_webhook": "string",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "phone_number_id": "00000000-0000-0000-0000-000000000000",
  "call_list_id": "00000000-0000-0000-0000-000000000000",
  "call_schedule": {
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "start_hour": 0,
    "end_hour": 0,
    "days_of_week": [
      0
    ]
  },
  "campaign_config": {
    "call_timeout_seconds": 0,
    "retry_attempts": 0,
    "retry_delay_seconds": 0,
    "retry_outcomes": [
      "string"
    ]
  }
}
'

shell

Example Request Body

{
  "name": "string",
  "description": "string",
  "status_webhook": "string",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "phone_number_id": "00000000-0000-0000-0000-000000000000",
  "call_list_id": "00000000-0000-0000-0000-000000000000",
  "call_schedule": {
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "start_hour": 0,
    "end_hour": 0,
    "days_of_week": [
      0
    ]
  },
  "campaign_config": {
    "call_timeout_seconds": 0,
    "retry_attempts": 0,
    "retry_delay_seconds": 0,
    "retry_outcomes": [
      "string"
    ]
  }
}

json

Example Responses

No example specified for this content type

application/json

Delete Campaign

DELETE

https://api.neuratel.ai

/v1/campaigns/{campaign_id}

Permanently delete an outbound campaign.

Delete Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Delete Campaign › Responses

Successful Response

No data returned

Start Campaign

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/start

Start an outbound campaign to begin making calls.

Start Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Start Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Pause Campaign

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/pause

Pause a running campaign. Can be resumed later.

Pause Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Pause Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Stop Campaign

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/stop

Soft halt — cancels queued calls. Restartable via /start, which creates fresh attempts for any contact whose attempts are all in terminal-non-success states. Use /cancel for a terminal kill switch.

Stop Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Stop Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Resume Campaign

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/resume

Resume a paused campaign (paused → active). Requeues the VoiceSessions that pause cancelled.

Resume Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Resume Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Cancel Campaign

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/cancel

Terminally cancel a campaign. Cannot be reversed — to reuse the config, duplicate the campaign first.

Cancel Campaign › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Cancel Campaign › Responses

Successful Response

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

Campaign Stats

GET

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/stats

Aggregate per-campaign call stats. Phase 1 sources from voice_sessions; Phase 3 sources from campaign_attempts.

Campaign Stats › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Campaign Stats › Responses

Successful Response

No data returned

Retry Failed Attempts

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/retry

Re-queue failed / no_answer / voicemail / busy attempts. Creates new CampaignAttempt rows with attempt_number = max+1 and fresh queued VoiceSessions, then enqueues dispatch.

Retry Failed Attempts › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Retry Failed Attempts › Request Body

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object
	type = null

Properties for CampaignRetryRequest:

Body for POST /campaigns/{id}/retry — re-dial failed attempts. Both filters are optional: - contact_ids: restrict the retry to these contacts only. - outcomes: only retry attempts whose latest outcome is in this set. Default: failed, no_answer, voicemail, busy. Creates one new CampaignAttempt per matched contact with attempt_number = max(prior attempts) + 1, then enqueues dispatch.

Restrict retry to these contacts (default: all matched)

Only retry attempts in these outcomes. Default: failed, no_answer, voicemail, busy.

Retry Failed Attempts › Responses

Successful Response

Result of POST /campaigns/{id}/retry.

requeued

integer · required

Number of new attempts created

contacts

string[]

Contact IDs that were retried

List Campaign Attempts

GET

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/attempts

Paginated list of per-contact dial attempts with optional outcome filter. Sources from the campaign_attempts table (Phase 1).

List Campaign Attempts › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

List Campaign Attempts › query Parameters

outcome

Filter by outcome (e.g. 'failed', 'completed', 'pending').

skip

integer · min: 0

Default: 0

limit

integer · min: 1 · max: 200

Default: 50

List Campaign Attempts › Responses

Successful Response

Paginated list of CampaignAttempt rows for GET /campaigns/{id}/attempts.

object[] · required

object · required

Pagination metadata in API responses.

GET/v1/campaigns/{campaign_id}/attempts

curl --request GET \
  --url https://api.neuratel.ai/v1/campaigns/:campaign_id/attempts

shell

Example Responses

{
  "results": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "campaign_id": "00000000-0000-0000-0000-000000000000",
      "contact_id": "00000000-0000-0000-0000-000000000000",
      "attempt_number": 0,
      "outcome": "outcome",
      "error_message": "string",
      "scheduled_for": "2024-08-25T15:00:00Z",
      "dispatched_at": "2024-08-25T15:00:00Z",
      "completed_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "metadata": {
    "count": 100,
    "has_more": true,
    "limit": 100,
    "skip": 0,
    "total": 250
  }
}

json

application/json

Test Status Webhook

POST

https://api.neuratel.ai

/v1/campaigns/{campaign_id}/test-webhook

Fires a synthetic campaign.test payload at the campaign's configured status_webhook URL so operators can verify their receiver before going live. Distinct event type from real lifecycle webhooks; receivers should ignore this event.

Test Status Webhook › path Parameters

campaign_id

string · uuid · required

The unique identifier of the campaign.

Test Status Webhook › Responses

Successful Response

Result of POST /campaigns/{id}/test-webhook. The endpoint fires a synthetic ``campaign.test`` payload against the campaign's configured ``status_webhook`` URL so the operator can verify their receiver before going live. Receivers should ignore this event type — it's distinct from real lifecycle events (``campaign.completed``, ``campaign.stopped``, ``campaign.failed``).

success

boolean · required

True if the receiver responded 2xx.

latency_ms

integer · required

Round-trip time in milliseconds.

HTTP status code from the receiver.

Truncated response body (first 500 chars).

Set when the request failed before getting a response.

List Campaign Calls

GET

https://api.neuratel.ai

/v1/campaigns/calls

List outbound call records generated by campaigns. Filter by campaign_id to get calls for a specific campaign. For one-off dialer calls use GET /v1/voice-sessions?channel=phone&direction=outbound.

List Campaign Calls › query Parameters

organization_id

deprecated

(Legacy) Organization id. Ignored; org is derived from auth context.

campaign_id

Filter by campaign id

status

Filter by call status

phone_number

Filter by destination phone number

skip

integer · min: 0

Number of records to skip

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return

Default: 100

List Campaign Calls › Responses

Successful Response

No data returned

Get Campaign Call

GET

https://api.neuratel.ai

/v1/campaigns/calls/{call_id}

Retrieve a specific campaign outbound call record by id.

Get Campaign Call › path Parameters

call_id

string · uuid · required

The unique identifier of the outbound call.

Get Campaign Call › Responses

Successful Response

One voice session — phone, web, or WhatsApp voice.

id

string · uuid · required

channel

string · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

analysis_status

string

Default: pending

retry_count

integer

Default: 0

duration_seconds

integer

Default: 0

object[]

object[] · maxItems: 5

conversation_turn_count

integer

Default: 0

sentiment_trend

number[]

topics_discussed

string[]

keywords_extracted

string[]

object

object[]

object

topics

string[]

action_items

string[]

object

GET/v1/campaigns/calls/{call_id}

curl --request GET \
  --url https://api.neuratel.ai/v1/campaigns/calls/:call_id

shell

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "channel": "channel",
  "direction": "string",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "agent_name": "string",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "phone_number_id": "00000000-0000-0000-0000-000000000000",
  "whatsapp_account_id": "00000000-0000-0000-0000-000000000000",
  "from_number": "string",
  "to_number": "string",
  "participant_address": "string",
  "business_address": "string",
  "caller_id": "string",
  "status": "status",
  "analysis_status": "pending",
  "call_result": "string",
  "failure_reason": "string",
  "error_message": "string",
  "end_reason": "string",
  "retry_count": 0,
  "started_at": "2024-08-25T15:00:00Z",
  "answered_at": "2024-08-25T15:00:00Z",
  "ended_at": "2024-08-25T15:00:00Z",
  "duration_seconds": 0,
  "billed_amount": 0,
  "billing_currency": "string",
  "billable_minutes": 0,
  "billing_rate_per_minute": 0,
  "participants": [
    {
      "participant_identity": "participant_identity",
      "participant_type": "participant_type",
      "joined_at": "2024-08-25T15:00:00Z",
      "left_at": "2024-08-25T15:00:00Z",
      "duration_seconds": 0
    }
  ],
  "agent_metrics": {
    "latency_ttft_ms": 0,
    "latency_ttfb_ms": 0,
    "eou_delay_ms": 0,
    "conversation_quality_score": 0,
    "sentiment_score": 0,
    "session_duration_seconds": 0,
    "extracted_data": {},
    "llm_tokens_prompt": 0,
    "llm_tokens_completion": 0,
    "llm_tokens_total": 0,
    "stt_provider": "string",
    "stt_model": "string",
    "stt_audio_duration_seconds": 0,
    "llm_provider": "string",
    "llm_model": "string",
    "tts_provider": "string",
    "tts_model": "string",
    "tts_characters": 0,
    "estimated_cost_usd": 0
  },
  "conversation_preview": [
    {
      "speaker": "speaker",
      "text": "text",
      "timestamp": "2024-08-25T15:00:00Z",
      "sentiment_score": 0,
      "sentiment_label": "string",
      "speaker_id": "string",
      "speaker_confidence": 0
    }
  ],
  "conversation_turn_count": 0,
  "conversation": [
    {
      "speaker": "speaker",
      "text": "text",
      "timestamp": "2024-08-25T15:00:00Z",
      "sentiment_score": 0,
      "sentiment_label": "string",
      "speaker_id": "string",
      "speaker_confidence": 0
    }
  ],
  "sentiment_trend": [
    0
  ],
  "topics_discussed": [
    "string"
  ],
  "keywords_extracted": [
    "string"
  ],
  "extracted_data": {},
  "usage_metrics": {
    "stt": {},
    "llm": {},
    "tts": {},
    "realtime": {}
  },
  "estimated_cost_usd": 0,
  "tool_calls": [
    {}
  ],
  "latency": {},
  "call_summary": "string",
  "success_evaluation": {},
  "sentiment_timeline": {
    "trend": "trend",
    "average_sentiment": 0,
    "high_point": {},
    "low_point": {},
    "turns": [
      {
        "turn": 0,
        "role": "role",
        "text": "text",
        "sentiment": 0,
        "emotion": "emotion"
      }
    ]
  },
  "audio_quality": {},
  "topics": [
    "string"
  ],
  "action_items": [
    "string"
  ],
  "user_sentiment": "string",
  "user_sentiment_score": 0,
  "call_successful": "string",
  "call_successful_rationale": "string",
  "evaluation_score": {},
  "recording": {
    "id": "00000000-0000-0000-0000-000000000000",
    "recording_url": "string",
    "status": "pending",
    "duration_seconds": 0,
    "file_size_bytes": 0,
    "format": "string",
    "error_message": "string",
    "created_at": "2024-08-25T15:00:00Z"
  },
  "session_id": "string",
  "call_metadata": {},
  "contact_data": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

List Call Lists

GET

https://api.neuratel.ai

/v1/lists

List call lists for your organization.

List Call Lists › query Parameters

skip

integer · min: 0

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

Default: 0

limit

integer · min: 1 · max: 100

Maximum number of records to return. Defaults to 50. Max 100.

Default: 50

List Call Lists › Responses

Successful Response

Paginated list of call lists. Standardized pagination format: - results: List of call lists - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

Create Call List

POST

https://api.neuratel.ai

/v1/lists

Create a new call list.

Create Call List › Request Body

Schema for creating call lists

name

string · minLength: 1 · maxLength: 255 · required

Call list name

Call list description

Create Call List › Responses

Successful Response

Schema for call list responses

name

string · minLength: 1 · maxLength: 255 · required

Call list name

id

string · uuid · required

organization_id

string · uuid · required

created_at

string · date-time · required

updated_at

string · date-time · required

Call list description

total_contacts

integer

Default: 0

active_contacts

integer

Default: 0

is_active

boolean

Default: true

Get Call List

GET

https://api.neuratel.ai

/v1/lists/{call_list_id}

Retrieve a specific call list by ID.

Get Call List › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Get Call List › Responses

Successful Response

Schema for call list responses

name

string · minLength: 1 · maxLength: 255 · required

Call list name

id

string · uuid · required

organization_id

string · uuid · required

created_at

string · date-time · required

updated_at

string · date-time · required

Call list description

total_contacts

integer

Default: 0

active_contacts

integer

Default: 0

is_active

boolean

Default: true

Update Call List

PUT

https://api.neuratel.ai

/v1/lists/{call_list_id}

Update a call list's properties.

Update Call List › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Update Call List › Request Body

Schema for updating call lists

Call list name

Call list description

Additional list metadata

List active status

Update Call List › Responses

Successful Response

Schema for call list responses

name

string · minLength: 1 · maxLength: 255 · required

Call list name

id

string · uuid · required

organization_id

string · uuid · required

created_at

string · date-time · required

updated_at

string · date-time · required

Call list description

total_contacts

integer

Default: 0

active_contacts

integer

Default: 0

is_active

boolean

Default: true

Delete Call List

DELETE

https://api.neuratel.ai

/v1/lists/{call_list_id}

Permanently delete a call list and all its contacts.

Delete Call List › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Delete Call List › Responses

Successful Response

No data returned

Get Contact Import Progress

GET

https://api.neuratel.ai

/v1/lists/import-jobs/{job_id}

Poll endpoint for the async contact-import path. The FE hits this every ~2s while a job is running. Snapshot lives in Redis for 1h after completion.

Get Contact Import Progress › path Parameters

job_id

string · required

Job id returned from POST /contacts/import.

Get Contact Import Progress › Responses

Successful Response

Progress snapshot for the GET /call-lists/import-jobs/{job_id} poll.

status

string · required

queued | running | completed | failed

total

integer

Default: 0

processed

integer

Default: 0

imported

integer

Default: 0

skipped

integer

Default: 0

dnc_blocked

integer

Default: 0

object[]

List Contacts

GET

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts

List contacts in a call list.

List Contacts › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

List Contacts › query Parameters

skip

integer · min: 0

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

Default: 0

limit

integer · min: 1 · max: 100

Maximum number of records to return. Defaults to 50. Max 100.

Default: 50

List Contacts › Responses

Successful Response

No data returned

Add Contact

POST

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts

Add a contact to a call list.

Add Contact › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Add Contact › Request Body

Schema for creating call list contacts

phone_number

string · minLength: 3 · maxLength: 20 · required

Contact phone number

object

Arbitrary key/value map. Every key becomes a {{key}} variable available to the agent prompt at call time. Reserved keys phone_number and status are rejected (they would override the contact's real columns).

Add Contact › Responses

Successful Response

Schema for call list contact responses. Phase 1 dropped the `call_count`, `last_called`, `call_result` fields — per-attempt outcomes now live on campaign_attempts and are exposed via GET /v1/campaigns/{id}/attempts.

phone_number

string · minLength: 3 · maxLength: 20 · required

Contact phone number

id

string · uuid · required

call_list_id

string · uuid · required

created_at

string · date-time · required

object

status

string

Default: active

is_active

boolean

Default: true

Update Contact

PUT

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts/{contact_id}

Update a contact's information.

Update Contact › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

contact_id

string · uuid · required

The unique identifier of the contact.

Update Contact › Request Body

Schema for updating call list contacts.

Contact phone number

Replace the contact's variable map. Pass {} to clear; omit to leave unchanged. Reserved keys phone_number and status are rejected.

Contact status: active, dnc, invalid, opted_out, or called (legacy)

Contact active status

Update Contact › Responses

Successful Response

phone_number

string · minLength: 3 · maxLength: 20 · required

Contact phone number

id

string · uuid · required

call_list_id

string · uuid · required

created_at

string · date-time · required

object

status

string

Default: active

is_active

boolean

Default: true

Delete Contact

DELETE

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts/{contact_id}

Remove a contact from a call list.

Delete Contact › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

contact_id

string · uuid · required

The unique identifier of the contact.

Delete Contact › Responses

Successful Response

No data returned

Preview Contact Import

POST

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts/preview

Step 1 of the two-step CSV import. Parses the uploaded file, detects encoding + delimiter, and returns a suggested header → canonical-field mapping plus a sample of rows. The opaque preview_token in the response is required for POST /import.

Preview Contact Import › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Preview Contact Import › Request Body

file

string · binary · required

CSV file with contact data (max 25MB).

Preview Contact Import › Responses

Successful Response

What POST /call-lists/{id}/contacts/preview returns. The FE renders a column-mapping screen using ``detected_headers`` + ``suggested_mapping``. The user can override any mapping, then POSTs back to /import with the ``preview_token``.

preview_token

string · required

Opaque token to pass to /import. TTL ~10 minutes.

detected_headers

string[] · required

total_rows

integer · required

encoding

string · required

delimiter

string · required

object

raw_header → canonical_field mapping derived from header aliases.

object[]

First 10 rows with raw cell values.

object[]

First 10 invalid rows with reasons.

Commit Contact Import

POST

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts/import

Step 2 of the two-step CSV import. Files >= 1000 rows are processed in the background via ARQ; smaller files run inline and return the final result.

Commit Contact Import › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Commit Contact Import › Request Body

Body for POST /call-lists/{id}/contacts/import. ``mapping`` overrides ``suggested_mapping`` from the preview step. Headers omitted from ``mapping`` are imported into ``contact_data`` so dynamic-variable agents can still address them.

preview_token

string · required

object

run_async

boolean

Force the background path. Auto-on for files >1000 rows; the FE may also opt in to background mode for smaller files to keep the UI responsive.

Default: false

Commit Contact Import › Responses

Successful Response

One of two shapes depending on ``run_async``: - sync: returns the final result inline. - async: returns ``{job_id, status: "queued"}`` and the FE polls GET /call-lists/import-jobs/{job_id} for progress.

status

string · required

queued | completed | failed

Set when run_async is true; poll for progress.

imported_count

integer

Default: 0

skipped_count

integer

Default: 0

dnc_blocked_count

integer

Default: 0

object[]

Bulk-paste Contacts

POST

https://api.neuratel.ai

/v1/lists/{call_list_id}/contacts/bulk

Manual bulk add for the FE bulk-paste tab. Up to 500 rows per call. Phone numbers are normalized to E.164 server-side; rows that fail to parse are returned in the errors array but the rest of the batch still imports.

Bulk-paste Contacts › path Parameters

call_list_id

string · uuid · required

The unique identifier of the call list.

Bulk-paste Contacts › Request Body

POST /call-lists/{id}/contacts/bulk — manual bulk-paste from FE.

object[] · minItems: 1 · maxItems: 500 · required

Bulk-paste Contacts › Responses

Successful Response

Result of /contacts/bulk.

imported_count

integer

Default: 0

skipped_count

integer

Default: 0

dnc_blocked_count

integer

Default: 0

object[]

API Keys Voice