Skip to main content
PATCH
/
campaigns
/
{id}
Update a campaign
curl --request PATCH \
  --url https://api.dialnexa.com/v1/campaigns/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "max_concurrent_calls": 123,
  "retry_config": {}
}
'
{
  "id": "cmp_xyz789",
  "organization_id": "org_xyz",
  "name": "Q2 Lead Re-engagement",
  "agent_id": "agt_abc123",
  "from_phone_number": "+912234567890",
  "status": "running",
  "max_concurrent_calls": 5,
  "scheduled_at": null,
  "retry_config": {
    "max_retries": 3,
    "retry_interval_minutes": 120
  },
  "created_at": "2024-03-01T09:00:00.000Z"
}
Updates editable settings on a campaign. You can change the display name, adjust max_concurrent_calls, modify the retry policy, and change other operational parameters at any time. Only the fields you include in the request are updated, omitted fields are left unchanged. The assigned agent_id cannot be changed once any calls have been placed, because doing so would split the campaign’s call logs across two different conversational policies and confuse downstream reporting.

​
When to use this

  • Concurrency tuning: increase max_concurrent_calls after observing that the campaign is under-utilizing capacity, or decrease it if you need to pace dialling more carefully.
  • Renaming: keep the campaign’s display name aligned with the business process it serves.
  • Retry policy changes: adjust how aggressively DialNexa retries no-answer or busy outcomes. See Auto-retry.
  • Pausing: set status-related fields to pause delivery while leaving the campaign’s configuration in place.
If you need to swap the agent after calls have started, the cleanest path is to cancel the existing campaign through the dashboard and create a new one with the new agent, that keeps each campaign’s call logs traceable to exactly one agent configuration.

​
Path parameters

ParameterDescription
idThe campaign ID, for example cmp_5tw8vz2rnx1q.

​
Body parameters

FieldDescription
nameNew display name.
max_concurrent_callsNew concurrency cap. Subject to the workspace concurrency limit, see Concurrency and limits.
retry_policyNew retry configuration.

​
Errors

  • 404 Not Found is returned when the campaign does not exist.
  • 400 Bad Request is returned when a field fails validation.
  • 409 Conflict is returned when you try to change agent_id after calls have been placed.

​
Request

curl -X PATCH "https://api.dialnexa.com/v1/campaigns/cmp_5tw8vz2rnx1q" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_concurrent_calls": 10}'

​
Response

{
  "id": "cmp_5tw8vz2rnx1q",
  "name": "Q2 Lead Re-engagement",
  "status": "active",
  "agent_id": "agt_k7m2nq9xw4p8",
  "from_phone_number": "+912234567890",
  "max_concurrent_calls": 10,
  "total_leads": 1200,
  "completed_calls": 438,
  "pending_calls": 762,
  "created_at": "2024-05-01T09:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

​
id
string
required

Body

application/json
​
name
string
​
max_concurrent_calls
integer
​
retry_config
object

Response

Success.

​
id
string
Example:

"cmp_xyz789"

​
organization_id
string
Example:

"org_xyz"

​
name
string
Example:

"Q2 Lead Re-engagement"

​
agent_id
string
Example:

"agt_abc123"

​
from_phone_number
string
Example:

"+912234567890"

​
status
enum<string>

Batch campaign lifecycle status.

Available options:
draft,
active,
running,
paused,
completed,
cancelled
Example:

"running"

​
max_concurrent_calls
integer
Example:

5

​
scheduled_at
string<date-time> | null
Example:

null

​
retry_config
object
Example:
{
  "max_retries": 3,
  "retry_interval_minutes": 120
}
​
created_at
string<date-time>
Example:

"2024-03-01T09:00:00.000Z"