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
}

​
Campaign Start Process

This endpoint starts a previously uploaded campaign by initiating outbound calls to all contacts in the specified campaign list.
Before starting a campaign, ensure you have:
  • Uploaded a contact list using the campaign upload endpoint
  • Configured your agent with the appropriate prompts and settings
  • Set up valid from_numbers that are provisioned for your workspace

​
Request Parameters

ParameterTypeRequiredDescription
agent_idstring✅ID of the agent that will handle all campaign calls
list_idstring✅ID of the uploaded campaign contact list
from_numbersarray✅Phone numbers to use for outbound calls

​
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