# 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": ![](/media/56/56f87e7ed04c0152bd4e9224b215fcf6c3b184e55cc93868c2c1795bdd0184d7.png) ## Campaign object > Example Campaign: ```json { "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" } ] } } ``` ### Top-level fields | 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](#greeting). | | `timers` | array | Pixel/postback timers — see [Timer](#timer). | | `menu_options` | array | IVR menu routing — see [Menu Option](#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](#postback-key). | ### Greeting | 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 | 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. | ### Menu Option | 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\ | 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\ | Target IDs for multi-target routing. | | `target_group_ids` | array\ | Target Group IDs for multi-target routing. | ### Postback Key | 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 ```shell curl "https://api.retreaver.com/campaigns.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json [ { "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": [] } } ] ``` 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 ```shell curl "https://api.retreaver.com/campaigns/cid/0044.json?api_key=[api_key]&company_id=1" ``` 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 | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `cid` | string | Your external campaign ID (`client_cid`). | ## Create a Campaign ```shell 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" } ] } }' ``` > 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. | 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](#timer-attributes). | | `menu_options_attributes` | array | | Array of menu option objects — see [Menu option attributes](#menu-option-attributes). | | `destroy_nested` | boolean | `false` | When `true`, destroys existing timers and menu options before applying the submitted values. | #### Timer attributes | 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 option attributes 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. | 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 ```shell 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"}}' ``` > 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](#create-a-campaign). > [!TIP] > To replace all existing timers with a new set: > ```json > { > "campaign": { > "destroy_nested": true, > "timers_attributes": [ > { "seconds": 0, "url": "https://example.com/click" }, > { "seconds": 60, "url": "https://example.com/sale" } > ] > } > } > ``` ## Delete a Campaign ```shell curl -X DELETE "https://api.retreaver.com/campaigns/cid/0044.json?api_key=[api_key]&company_id=1" ``` 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.