Skip to main content
POST
/
campaign
/
start
Start Campaign
curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/campaign/start \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "list_id": "123e4567-e89b-12d3-a456-426614174000",
  "from_numbers": [
    "+1234567890"
  ]
}
'
{
  "status": "campaign registered successfully!",
  "has_ongoing_calls": false
}
Deprecated. This endpoint requires you to pass and manage from_numbers yourself. New integrations should use Start Campaign (Pool), which resolves numbers automatically from a managed pool (rotation, spam skipping, and auto-purchase).
Start a campaign that was created with POST /campaign/save. This is the legacy start endpoint for the standard campaign flow. The endpoint schedules outbound calls for all valid contacts in the uploaded campaign list.
Before starting a campaign, ensure you have:
  • Uploaded a contact list using Upload campaign contact list
  • Configured your agent with the appropriate prompts and settings
  • Selected valid from_numbers that are provisioned for your workspace

​
Request parameters

ParameterTypeRequiredDescription
agent_idstringYesID of the agent that will handle all campaign calls
list_idstringYesID of the uploaded campaign contact list
from_numbersarrayYesWorkspace caller numbers or number IDs to use for outbound calls

​
Standard flow

  1. Upload contacts with Upload campaign contact list.
  2. Save the returned list_id.
  3. Start calls with this endpoint.
  4. Monitor progress with Get all campaigns and call history filtered by bulk_list_id.

​
Beta large-campaign start

Do not use this endpoint for the beta 5,000+ row flow. After POST /campaign/upload-csv, wait for upload processing to complete, check balance, then start calls with Make large campaign calls async.

​
Important notes

  • Credits Required: Ensure your workspace has sufficient credits for all contacts in the campaign
  • International Calls: For international numbers, only Twilio from_numbers are supported
  • Campaign Status: Once started, the campaign status changes to “scheduled” or “ongoing”
  • Duplicate Prevention: Cannot start a campaign that’s already in “scheduled” or “ongoing” status

​
Error responses

  • 400: Invalid agent_id, campaign not found, insufficient credits, or campaign already started
  • 401: Invalid or missing API key
  • 404: Campaign or agent not found
  • 402: Insufficient credits to initiate campaign

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Body

application/json
​
agent_id
string
required

(Required) ID of the agent that will handle the calls.

Example:

"830f767a-397e-4b39-82ff-235cd344e2f9"

​
list_id
string
required

(Required) ID of the uploaded campaign contact list.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
from_numbers
string[]
required

(Required) Array of phone numbers to use for outbound calls.

Example:
["+1234567890", "+0987654321"]

Response

Campaign started successfully.

​
status
string

Success message indicating campaign registration

Example:

"campaign registered successfully!"

​
has_ongoing_calls
boolean

Whether the workspace has other ongoing calls

Example:

false