Campaigns API

Campaigns define routing settings, greetings, timers, and IVR menu options that can be reused across multiple Numbers. Configure Campaigns before creating the Numbers that reference them.

Each Campaign has a cid — your external identifier for the campaign. If you don’t supply one on create, Retreaver auto-generates a random 8-character CID. Campaigns also have a Retreaver-assigned internal id, but most API endpoints operate on cid.

You can find a Campaign’s CID by visiting the Campaign detail page, under “Campaign ID”:

Campaign object

Example Campaign:

{
  "campaign": {
    "id": 9872,
    "cid": "0044",
    "name": "SuperFuntime",
    "record_calls": true,
    "record_seconds": 3600,
    "dedupe_seconds": 86400,
    "affiliate_can_pull_number": false,
    "show_key": "5e2ba674a8a1fb34dddcf850139ffdd9",
    "paused": false,
    "paused_at": null,
    "created_at": "2012-04-16T13:50:21Z",
    "updated_at": "2012-07-15T03:40:24Z",
    "greeting": {
      "message": "Hi there! Press one to continue.",
      "voice_gender": "Female",
      "repeat": 4,
      "audio_file_name": null,
      "audio_file_content_type": null,
      "audio_file_size": null,
      "audio_file_updated_at": null
    },
    "timers": [
      {
        "timer": {
          "id": 195,
          "seconds": 0,
          "url": "https://example.com/click?cid=[campaign_id]&afid=[affiliate_id]",
          "dedupe_seconds": null,
          "type": null,
          "afid": null,
          "tid": null
        }
      },
      {
        "timer": {
          "id": 199,
          "seconds": 90,
          "url": "https://example.com/sale?cid=[campaign_id]&afid=[affiliate_id]",
          "dedupe_seconds": null,
          "type": null,
          "afid": null,
          "tid": null
        }
      }
    ],
    "menu_options": [
      {
        "menu_option": {
          "id": 61,
          "option": "1",
          "options": ["1"],
          "action": 0,
          "target_number": "+18987748833",
          "target_cid": null,
          "target_ids": [],
          "target_group_ids": []
        }
      }
    ],
    "postback_keys": [
      {
        "name": "Sale",
        "action": "sale",
        "url": "https://api.retreaver.com/postback/…",
        "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ]
  }
}

Swipe horizontally for full code

Top-level fields

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Retreaver’s internal ID for the campaign.
`cid`	string	Your external campaign ID (client_cid).
`name`	string \| null	Human-readable campaign name.
`record_calls`	boolean	Whether calls on this campaign are recorded.
`record_seconds`	integer \| null	Maximum seconds of a call to record.
`dedupe_seconds`	integer	Suppresses repeat-caller timers within this window. `0` disables deduplication.
`affiliate_can_pull_number`	boolean	Grants affiliates access via the LinkTrust integration.
`show_key`	string	Public tracking key for this campaign.
`paused`	boolean \| null	Whether the campaign is paused.
`paused_at`	string \| null	Timestamp when the campaign was paused.
`created_at` / `updated_at`	string (ISO 8601)	Creation and last-modified timestamps.
`greeting`	object	Greeting configuration — see Greeting.
`timers`	array	Pixel/postback timers — see Timer.
`menu_options`	array	IVR menu routing — see Menu Option.
`targets`	array \| null	Targets attached to the campaign (only present when the caller has Target read permission).
`number_pools`	array \| null	Number Pools attached to this campaign.
`postback_keys`	array	Postback API URLs — see Postback Key.

Greeting

Swipe horizontally to view full table

Field	Type	Description
`message`	string \| null	Text-to-speech greeting text.
`voice_gender`	string \| null	`Male` or `Female`.
`repeat`	integer \| null	Number of times the greeting is repeated.
`audio_file_name`	string \| null	Uploaded audio filename, if any.
`audio_file_content_type`	string \| null	Uploaded audio MIME type.
`audio_file_size`	integer \| null	Uploaded audio size in bytes.
`audio_file_updated_at`	string \| null	Last time the audio file was updated.

Timer

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Internal ID of the timer. Pass this when updating.
`seconds`	integer	Minimum call duration before this timer fires. `0` fires at call start (click timer); `>0` fires at that sale threshold.
`url`	string	URL to fire when the timer triggers. Supports token interpolation (`[campaign_id]`, `[caller_id]`, etc.).
`dedupe_seconds`	integer \| null	Per-timer dedupe override.
`type`	string \| null	Timer subtype.
`afid`	string \| null	Affiliate client ID this timer is scoped to.
`tid`	string \| null	Target client ID this timer is scoped to.

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Internal ID of the menu option. Pass this when updating.
`option`	string	The DTMF key the caller presses (`0`–`9`, `*`, `#`).
`options`	array<string>	All configured option keys for this routing rule.
`action`	integer	Routing action type.
`target_number`	string \| null	Phone number to route the call to.
`target_cid`	string \| null	Campaign CID to route the caller to. Overrides `target_number` when set.
`target_ids`	array<integer>	Target IDs for multi-target routing.
`target_group_ids`	array<integer>	Target Group IDs for multi-target routing.

Postback Key

Swipe horizontally to view full table

Field	Type	Description
`name`	string	Display name for the postback key.
`action`	string	The action this postback corresponds to.
`url`	string	The postback URL template.
`key`	string	Unique UUID for this postback key.

List all Campaigns

curl "https://api.retreaver.com/campaigns.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

The above command returns JSON structured like this:

[
  {
    "campaign": {
      "id": 9872,
      "cid": "0044",
      "name": "SuperFuntime",
      "record_calls": true,
      "record_seconds": 3600,
      "dedupe_seconds": 86400,
      "affiliate_can_pull_number": false,
      "show_key": "5e2ba674a8a1fb34dddcf850139ffdd9",
      "created_at": "2012-04-16T13:50:21Z",
      "updated_at": "2012-07-15T03:40:24Z",
      "greeting": { "message": "Hi there! Press one to continue.", "voice_gender": "Female" },
      "timers": [],
      "menu_options": []
    }
  }
]

Swipe horizontally for full code

Returns all Campaigns for the authenticated Company.

HTTP Request

GET https://api.retreaver.com/campaigns.json?api_key=[api_key]&company_id=1

Get a specific Campaign

curl "https://api.retreaver.com/campaigns/cid/0044.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Returns a Campaign by your external CID.

HTTP Request

GET https://api.retreaver.com/campaigns/cid/{cid}.json?api_key=[api_key]&company_id=1

Path Parameters

Swipe horizontally to view full table

Parameter	Type	Description
`cid`	string	Your external campaign ID (`client_cid`).

Create a Campaign

curl -s \
    -X POST \
    "https://api.retreaver.com/campaigns.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{
          "campaign": {
            "cid": "000333",
            "name": "MyCampaign",
            "message": "Thanks for calling, please press 1 to continue.",
            "voice_gender": "Male",
            "timers_attributes": [
              { "seconds": 0,  "url": "https://example.com/click" },
              { "seconds": 90, "url": "https://example.com/sale"  }
            ],
            "menu_options_attributes": [
              { "option": "1", "target_number": "+16474570424" }
            ]
          }
        }'

Swipe horizontally for full code

The above command returns the newly created Campaign object.

Creates a new Campaign.

If you don’t provide any menu_options_attributes, Retreaver automatically creates a default menu option for key 1 — this is the default routing path used when no IVR greeting is configured.

Greeting options (pick one):

message + voice_gender — text-to-speech.
message_file — upload an audio file using multipart/form-data.
message_file_b64_data + message_file_b64_filename — submit an audio file inline as Base64 (useful for pure JSON clients).

Timers: A 0-second timer fires at call start (click). A >0-second timer fires when the call reaches that duration (sale). Only the highest-applicable sale timer fires per call — if you have 30s and 90s timers and a call lasts 2 minutes, only the 90s timer fires.

HTTP Request

POST https://api.retreaver.com/campaigns.json?api_key=[api_key]&company_id=1

Content-Type: application/json

Body Parameters

All parameters must be nested under a campaign key.

Swipe horizontally to view full table

Parameter	Type	Default	Description
`cid`	string	Random 8 characters	Your external campaign ID. Auto-generated if omitted.
`name`	string		A label for the campaign.
`dedupe_seconds`	integer	`0`	Suppress duplicate connect/sale timers for the same caller within this window. `0` disables deduplication.
`affiliate_can_pull_number`	boolean	`false`	Allow affiliates to access this campaign via the LinkTrust integration.
`record_calls`	boolean	`true`	Toggle call recording.
`record_seconds`	integer		Maximum seconds to record per call.
`message`	string		Text-to-speech. Greeting message read to the caller. Instruct them to press `1` to continue.
`voice_gender`	string	`Female`	Text-to-speech. `Male` or `Female`.
`message_file`	file		Audio file. Upload via `multipart/form-data`.
`message_file_b64_data`	string		Audio file. Base64-encoded audio. Use instead of `message_file` when sending JSON.
`message_file_b64_filename`	string		Audio file. Original filename for the Base64 audio (e.g. `memo.flac`). Use the highest quality audio available.
`repeat`	integer	`4`	Number of times to repeat the greeting.
`timers_attributes`	array		Array of timer objects — see Timer attributes.
`menu_options_attributes`	array		Array of menu option objects — see Menu option attributes.
`destroy_nested`	boolean	`false`	When `true`, destroys existing timers and menu options before applying the submitted values.

Timer attributes

Swipe horizontally to view full table

Parameter	Type	Required	Description
`id`	integer		Include when updating an existing timer.
`seconds`	integer	required	`0` fires at call start (click timer). `>0` fires when the call reaches that duration (sale timer).
`url`	string	required	URL to fire when the timer triggers. Cookies set on the click timer are passed through; redirects are followed.

Menu options route callers based on the DTMF key they press. You must provide at least one option for key 1 — this is the default path used when no IVR greeting is configured.

Swipe horizontally to view full table

Parameter	Type	Required	Description
`id`	integer		Include when updating an existing menu option.
`option`	string	required	DTMF key (`0`–`9`, `*`, `#`).
`target_number`	string		Phone number to route the caller to. All `>0` second timers start when the call is answered.
`target_cid`	string		Campaign CID to route the caller to. Overrides `target_number` when set — can be used to replay a different greeting.

Update a Campaign

curl -s \
    -X PUT \
    "https://api.retreaver.com/campaigns/cid/0044.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{"campaign":{"name":"My Other Campaign"}}'

Swipe horizontally for full code

The above command returns the updated Campaign object.

Updates any attributes on the Campaign. Only fields you pass are changed — omitted fields remain untouched.

Updating nested attributes:

To add a new timer or menu option, pass it in timers_attributes or menu_options_attributes without an id.
To update an existing timer or menu option, include its id in the submitted object.
To replace all timers/menu options, set destroy_nested: true and submit the new set.

Switching greeting type: Passing message switches the greeting to text-to-speech and clears any existing audio file upload.

HTTP Request

PUT https://api.retreaver.com/campaigns/cid/{cid}.json?api_key=[api_key]&company_id=1

Content-Type: application/json

Body Parameters

Accepts the same parameters as Create a Campaign.

Tip

To replace all existing timers with a new set:

{
  "campaign": {
    "destroy_nested": true,
    "timers_attributes": [
      { "seconds": 0,  "url": "https://example.com/click" },
      { "seconds": 60, "url": "https://example.com/sale"  }
    ]
  }
}

Swipe horizontally for full code

Delete a Campaign

curl -X DELETE "https://api.retreaver.com/campaigns/cid/0044.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Deletes a Campaign by CID.

HTTP Request

DELETE https://api.retreaver.com/campaigns/cid/{cid}.json?api_key=[api_key]&company_id=1

Note

Returns 400 if the Campaign still has Numbers or Number Pools attached. Delete those first, then retry.

Campaign object

Top-level fields

Greeting

Timer

Menu Option

Postback Key

List all Campaigns

HTTP Request

Get a specific Campaign

HTTP Request

Path Parameters

Create a Campaign

HTTP Request

Body Parameters

Timer attributes

Menu option attributes

Update a Campaign

HTTP Request

Body Parameters

Delete a Campaign

HTTP Request