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

name

string

required

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

script_id

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.

language

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).

contacts

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

contacts[].phone

string

required

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

contacts[].name

string

required

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

contacts[].*

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}.

schedule

object

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

Show Schedule object fields

schedule.start_time

string

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

schedule.end_time

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.

schedule.timezone

string

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

max_attempts

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.

retry_interval_minutes

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

status

string

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

from

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.

limit

integer

default:"20"

Number of results per page. Maximum 100.

offset

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.

name

string

Campaign display name.

status

string

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

total_contacts

integer

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

calls_made

integer

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

calls_connected

integer

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

disposition_summary

object

A breakdown of outcome counts by disposition label.

Show Disposition summary fields

disposition_summary.interested

integer

Contacts who expressed interest during the call.

disposition_summary.not_interested

integer

Contacts who declined or were not interested.

disposition_summary.callback

integer

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

disposition_summary.not_reachable

integer

Contacts who did not answer after all configured attempts.

disposition_summary.dnd

integer

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

disposition_summary.escalated

integer

Calls that were escalated to a human agent.

created_at

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

action

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

phones

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.

​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