Campaigns API — Create and Manage Calling Campaigns

Campaigns are the core organizing unit of VInfer Neuron. A campaign ties together a contact list, a voice script, a language, and a calling schedule into a single managed run. Once launched, Neuron dials each contact automatically, follows the script, records dispositions, and retries based on your configuration. The Campaigns API lets you create and control all of this programmatically — without touching the dashboard.

Create a Campaign

POST /campaigns Creates a new outbound calling campaign. The campaign starts in scheduled status and begins dialing at the configured start_time (or immediately if no schedule is set and you later call the start action).

Request Body

string

required

A human-readable display name for the campaign. Shown in the dashboard and included in webhook payloads. Maximum 255 characters.

string

required

The ID of the voice script to use. Scripts are created and managed in the Neuron section of the dashboard under Scripts. You can find the script ID on the script detail page.

string

required

BCP-47 language code for the campaign. Determines the voice model and speech recognition used during calls. Examples: hi-IN (Hindi), ta-IN (Tamil), en-IN (English — India).

array

required

Array of contact objects to call. Each contact must include phone (E.164 format, e.g. +919876543210) and name (string). You can also include any custom fields as additional key-value pairs on the contact object — they are passed into the script context at call time.

Show Contact object fields

string

required

The contact’s phone number in E.164 format. Must include the country code prefix (e.g., +91 for India).

string

required

The contact’s name. Used within the script for personalization (e.g., “Hello, ”).

any

Any additional fields you include are treated as custom variables available within the script template. For example, "loan_amount": "50000" can be referenced in the script as {loan_amount}.

object

Optional scheduling configuration. If omitted, the campaign can be started manually from the dashboard or via PATCH /campaigns/{id}.

Show Schedule object fields

string

ISO 8601 datetime at which the campaign should begin dialing. Example: 2024-02-01T09:00:00.

string

ISO 8601 datetime at which the campaign should stop, even if contacts remain. Calls already in progress when this time is reached are allowed to complete.

string

IANA timezone name for the start_time and end_time values. Example: Asia/Kolkata. Defaults to UTC if not specified.

integer

default:"1"

Maximum number of call attempts per contact. Accepted values are 1 through 5. Contacts that are not reachable after all attempts are marked with disposition not_reachable.

integer

default:"240"

Number of minutes to wait between retry attempts for a contact who was not reachable. Only applies when max_attempts is greater than 1.

Example Request

cURL

curl https://api.vinfer.ai/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Loan Renewal Outreach",
    "script_id": "scr_7xK2pL9mN",
    "language": "hi-IN",
    "contacts": [
      {"phone": "+919876543210", "name": "Priya Sharma", "loan_amount": "75000"},
      {"phone": "+918765432109", "name": "Rahul Verma", "loan_amount": "120000"}
    ],
    "schedule": {
      "start_time": "2024-02-01T09:00:00",
      "end_time": "2024-02-01T18:00:00",
      "timezone": "Asia/Kolkata"
    },
    "max_attempts": 3,
    "retry_interval_minutes": 120
  }'

Example Response

{
  "id": "cmp_4Rv8sT1wX",
  "name": "February Loan Renewal Outreach",
  "status": "scheduled",
  "script_id": "scr_7xK2pL9mN",
  "language": "hi-IN",
  "total_contacts": 2,
  "max_attempts": 3,
  "retry_interval_minutes": 120,
  "schedule": {
    "start_time": "2024-02-01T09:00:00",
    "end_time": "2024-02-01T18:00:00",
    "timezone": "Asia/Kolkata"
  },
  "created_at": "2024-01-28T14:22:10Z"
}

List Campaigns

GET /campaigns Returns a paginated list of campaigns in your workspace, ordered by creation date descending.

Query Parameters

string

Filter by campaign status. One of: scheduled, running, paused, completed, stopped.

string

ISO 8601 date — return campaigns created on or after this date. Example: 2024-01-01.

string

ISO 8601 date — return campaigns created on or before this date.

integer

default:"20"

Number of results per page. Maximum 100.

integer

default:"0"

Number of results to skip. Use with limit to paginate through results.

Example Request

curl "https://api.vinfer.ai/v1/campaigns?status=running&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Campaign Details

GET /campaigns/{id} Returns full details for a single campaign, including real-time progress counters and a breakdown of call dispositions.

Response Fields

string

Unique identifier for the campaign.

string

Campaign display name.

string

Current campaign status: scheduled, running, paused, completed, or stopped.

integer

Total number of contacts in the campaign (including contacts removed via the contacts endpoint).

integer

Number of call attempts made so far (including retries).

integer

Number of calls where the contact answered and the conversation began.

object

A breakdown of outcome counts by disposition label.

Show Disposition summary fields

integer

Contacts who expressed interest during the call.

integer

Contacts who declined or were not interested.

integer

Contacts who asked to be called back at a later time.

integer

Contacts who did not answer after all configured attempts.

integer

Contacts who requested to be added to the do-not-disturb list.

integer

Calls that were escalated to a human agent.

string

ISO 8601 timestamp of when the campaign was created.

Update Campaign Status

PATCH /campaigns/{id} Pauses, resumes, or stops a campaign that is currently running or paused. Pass an action field in the request body.

Request Body

string

required

The action to perform. One of:

pause — suspends dialing; calls already in progress are allowed to finish.
resume — resumes a paused campaign.
stop — permanently stops the campaign; cannot be restarted.

Example Request

curl https://api.vinfer.ai/v1/campaigns/cmp_4Rv8sT1wX \
  -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "pause"}'

The stop action is irreversible. A stopped campaign cannot be resumed. If you need to temporarily halt a campaign, use pause instead.

Remove Contacts from a Campaign

DELETE /campaigns/{id}/contacts Removes specific contacts from an active or scheduled campaign. Use this to apply DNC (Do Not Call) suppression after a campaign has already been created, or to remove contacts who have since converted through another channel.

Request Body

array

required

Array of phone numbers in E.164 format to remove from the campaign. Contacts who have already been called are not affected — only pending contacts are removed.

Example Request

curl https://api.vinfer.ai/v1/campaigns/cmp_4Rv8sT1wX/contacts \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+919876543210", "+918765432109"]}'

Example Response

{
  "removed": 2,
  "not_found": 0,
  "already_called": 0
}

Contacts that were already called before this request are counted in already_called and are not removed from the campaign record — their call data is preserved for reporting.

Overview

Neuron API

NeuronLens API

Campaigns API — Create and Manage Calling Campaigns

Create a Campaign

Request Body

Example Request

Example Response

List Campaigns

Query Parameters

Example Request

Get Campaign Details

Response Fields

Update Campaign Status

Request Body

Example Request

Remove Contacts from a Campaign

Request Body

Example Request

Example Response

​Create a Campaign

​Request Body

​Example Request

​Example Response

​List Campaigns

​Query Parameters

​Example Request

​Get Campaign Details

​Response Fields

​Update Campaign Status

​Request Body

​Example Request

​Remove Contacts from a Campaign

​Request Body

​Example Request

​Example Response

Create a Campaign

Request Body

Example Request

Example Response

List Campaigns

Query Parameters

Example Request

Get Campaign Details

Response Fields

Update Campaign Status

Request Body

Example Request

Remove Contacts from a Campaign

Request Body

Example Request

Example Response