Graine AI
API referenceCampaigns

Update a campaign

Change a campaign's dialling policy.

Change a campaign's dialling policy.

Send only the fields you are changing. Nested objects are REPLACED whole, not merged: a retry_policy with one key sets the rest back to their defaults, so send the object you want to end up with.

Every contact still waiting picks the new policy up on its next attempt; calls already in flight keep the settings they started with.

Two fields are deliberately absent. status moves through /pause, /resume, /cancel and DELETE, which also cascade to the batches — a campaign whose status says paused while its batches keep dialling is the worst state this system can be in. agent_id is fixed for the life of the campaign, because it is what the call history is attributed to.

A cancelled or archived campaign answers 409.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

PATCH
/v2/campaigns/{campaign_id}
/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

nameName | null

New label.

Maximum length: 200

phone_numbersPhone Numbers | null

Replacement caller ID set.

phone_number_strategyPhone Number Strategy | null

round_robin | random | least_loaded.

timezoneTimezone | null

New IANA timezone.

working_hours_enforcedWorking Hours Enforced | null

Turn window enforcement on or off.

working_hoursWorking Hours | null

Replacement windows. Sent whole — this is a replace, not a merge.

max_concurrent_callsMax Concurrent Calls | null

Ceiling on this campaign's SIMULTANEOUS calls. Omit for no campaign ceiling. It can only LOWER what the organisation's limit and the fair share across active campaigns already allow — raising it past the org limit has no effect.

Minimum: 1Maximum: 10000

retry_policyRetry Policy

Replacement retry policy. Sent whole.

follow_up_policyFollow Up Policy

Replacement follow-up policy. Sent whole.

transliterationTransliteration

Replacement transliteration config. Sent whole.

start_timeStart Time | null

ISO-8601 with a timezone offset.

end_timeEnd Time | null

ISO-8601 with a timezone offset. Pushing this into the future on a campaign that already completed or expired RE-ACTIVATES it — that is how a campaign is re-run.

default_call_variablesDefault Call Variables | null

Replacement variables.

default_call_contextDefault Call Context | null

Replacement context.

metadataMetadata | null

Replacement metadata.

Path Parameters

campaign_id
Required
Campaign Id

Campaign identifier.

Query Parameters

organization_idOrganization Id

Must match the organisation the API key belongs to.

Response Body

200

The campaign after the change.

batch_idBatch Id | null

The batch created from contacts on this request, if any were supplied. Null on every other read — a campaign can hold many batches; list them with GET /v2/campaigns/{campaign_id}/batches.

total_contactsTotal Contacts

Contacts across every batch.

Default: 0

campaign_id
Required
Campaign Id

Campaign identifier.

organization_idOrganization Id | null

The organisation this campaign belongs to. Always your own.

name
Required
Name | null

Human label for the campaign.

agent_id
Required
Agent Id | null

Agent that places every call.

phone_numbersPhone Numbers

Caller IDs this campaign dials from.

@minItems 0

phone_number_strategyPhone Number Strategy

round_robin | random | least_loaded.

Default: "round_robin"

phone_number_indexPhone Number Index

Round-robin cursor: the position the next call starts from.

Default: 0

timezoneTimezone

IANA timezone the working hours and the window are evaluated in.

Default: "UTC"

working_hours_enforcedWorking Hours Enforced

False dials around the clock, subject only to start_time/end_time.

Default: false

working_hoursWorking Hours

Per-day dialling windows, keyed by lowercase day name.

max_concurrent_callsMax Concurrent Calls | null

Ceiling on this campaign's SIMULTANEOUS calls. Omit for no campaign ceiling. It can only LOWER what the organisation's limit and the fair share across active campaigns already allow — raising it past the org limit has no effect.

retry_policy
Required
Retry Policy

What happens after a busy or a no-answer.

follow_up_policy
Required
Follow Up Policy

Callbacks after the first cycle ends.

transliteration
Required
Transliteration

Name-script rewriting inherited by every batch.

start_timeStart Time | null

ISO-8601 UTC. Nothing dials before this.

end_timeEnd Time | null

ISO-8601 UTC. Nothing dials after this; the campaign then expires.

default_call_variablesDefault Call Variables

Prompt variables applied to every call, overridable per contact.

default_call_contextDefault Call Context

Free-form context applied to every call.

status
Required
Status

created | active | paused | completed | cancelled | expired | archived. A campaign is born 'created' and becomes 'active' when its first batch dials. 'archived' is what DELETE leaves behind; 'cancelled' is what the cancel action does.

metadataMetadata

Whatever you stored on the campaign.

total_batchesTotal Batches

Batches created under this campaign.

Default: 0

active_batchesActive Batches

Batches not yet finished.

Default: 0

completed_contactsCompleted Contacts

Contacts that reached a completed call, counted ONCE regardless of how many attempts it took. Use this for progress, not completed_calls.

Default: 0

completed_callsCompleted Calls

Calls that completed, retries included.

Default: 0

failed_callsFailed Calls

Calls that failed.

Default: 0

busy_callsBusy Calls

Calls that hit a busy line.

Default: 0

no_answer_callsNo Answer Calls

Calls that rang out.

Default: 0

voicemail_callsVoicemail Calls

Calls answered by a voicemail box. A SUBSET of no_answer_calls, never a peer of it — do not add it to the others to form a total.

Default: 0

in_progress_callsIn Progress Calls

Calls live right now.

Default: 0

follow_up_callsFollow Up Calls

Follow-up calls placed.

Default: 0

follow_up_exhaustedFollow Up Exhausted

Contacts whose follow-up attempts ran out.

Default: 0

created_atCreated At | null

ISO-8601 UTC.

updated_atUpdated At | null

ISO-8601 UTC.

400

1000 — malformed or contradictory input: an unknown timezone, a working-hours window that is not 24-hour HH:MM, an end_time at or before start_time, or an empty patch body. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such campaign, or no such agent, in this organisation. A campaign belonging to another organisation answers 404, never 403, so ids cannot be probed.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

409

1201 — the campaign's state does not allow this action: resuming or cancelling a campaign that has already been cancelled, completed, expired or archived; editing a cancelled campaign; or deleting one that still has batches running.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — the agent service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — the agent service did not respond in time.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X PATCH "https://api.graine.ai/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328?organization_id=string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slot-2-Uttar-Pradesh",
    "phone_numbers": [
      "+917971442184"
    ],
    "phone_number_strategy": "round_robin",
    "timezone": "Asia/Kolkata",
    "working_hours_enforced": true,
    "working_hours": {
      "monday": {
        "start": "08:00",
        "end": "20:00",
        "enabled": true
      }
    },
    "max_concurrent_calls": 10,
    "retry_policy": {
      "max_retries": 5,
      "strategy": "fixed_delay",
      "cooldown_minutes": 45,
      "base_delay_minutes": 15,
      "max_delay_minutes": 240,
      "respect_working_hours": true
    },
    "follow_up_policy": {
      "enabled": false,
      "max_attempts": 2,
      "cooldown_minutes": 1440,
      "triggers": [
        "after_retries_exhausted"
      ],
      "next_working_day_only": true,
      "follow_up_agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
      "follow_up_prompt": "You spoke to this person yesterday. Open by referring to that call.",
      "follow_up_extra_logic": {}
    },
    "transliteration": {
      "enabled": true,
      "fields": [
        "callee_name"
      ],
      "target_language_code": "hi-IN",
      "source_language_code": "en-IN",
      "keep_original": true
    },
    "start_time": "2027-03-02T11:00:00+05:30",
    "end_time": "2027-03-09T16:30:00+05:30",
    "default_call_variables": {
      "campaign_offer": "monsoon-renewal"
    },
    "default_call_context": {},
    "metadata": {
      "region": "uttar-pradesh",
      "slot": "2"
    }
  }'

The campaign after the change.

{
  "batch_id": "fa08ae9d-239f-4a99-8d76-d4dec51311b4",
  "total_contacts": 3000,
  "campaign_id": "31ff3ea9-8bb5-433f-868f-286ac3c31328",
  "organization_id": "string",
  "name": "Slot-2-Uttar-Pradesh",
  "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
  "phone_numbers": [
    "+917971442184"
  ],
  "phone_number_strategy": "round_robin",
  "phone_number_index": 0,
  "timezone": "Asia/Kolkata",
  "working_hours_enforced": true,
  "working_hours": {
    "monday": {
      "start": "08:00",
      "end": "20:00",
      "enabled": true
    },
    "saturday": {
      "start": "10:00",
      "end": "16:00",
      "enabled": true
    },
    "sunday": {
      "start": "10:00",
      "end": "16:00",
      "enabled": false
    }
  },
  "max_concurrent_calls": 10,
  "retry_policy": {
    "max_retries": 5,
    "strategy": "fixed_delay",
    "cooldown_minutes": 45,
    "base_delay_minutes": 15,
    "max_delay_minutes": 240,
    "respect_working_hours": true
  },
  "follow_up_policy": {
    "enabled": false,
    "max_attempts": 2,
    "cooldown_minutes": 1440,
    "triggers": [
      "after_retries_exhausted"
    ],
    "next_working_day_only": true,
    "follow_up_agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
    "follow_up_prompt": "You spoke to this person yesterday. Open by referring to that call.",
    "follow_up_extra_logic": {}
  },
  "transliteration": {
    "enabled": true,
    "fields": [
      "callee_name"
    ],
    "target_language_code": "hi-IN",
    "source_language_code": "en-IN",
    "keep_original": true
  },
  "start_time": "2026-08-27T05:30:00.000Z",
  "end_time": "2026-08-31T11:00:00.000Z",
  "default_call_variables": {
    "campaign_offer": "monsoon-renewal"
  },
  "default_call_context": {},
  "status": "paused",
  "metadata": {
    "region": "uttar-pradesh",
    "slot": "2"
  },
  "total_batches": 1,
  "active_batches": 1,
  "completed_contacts": 412,
  "completed_calls": 451,
  "failed_calls": 88,
  "busy_calls": 37,
  "no_answer_calls": 120,
  "voicemail_calls": 14,
  "in_progress_calls": 3,
  "follow_up_calls": 0,
  "follow_up_exhausted": 0,
  "created_at": "2026-08-26T10:48:18.239Z",
  "updated_at": "2026-08-26T10:51:46.003Z"
}

Previous

Create a campaign POST

Next

Delete a campaign DELETE