# Numbers API Numbers are the physical phone numbers routed to a Campaign. A Number can forward directly to a Target, or play a greeting and route based on IVR menu options. By default, a Number inherits its greeting, timers, and route settings (menu options) from its Campaign — override these at the Number level only when you need per-Number behavior. Each Number belongs to exactly one Campaign and one Affiliate, identified by `cid` and `afid` respectively. ## Number object > Example Number: ```json { "number": { "id": 5, "number": "+16479311232", "country": "US", "toll_free": false, "sid": "superaffiliate", "afid": "0001", "cid": "111", "name": null, "uses_campaign_settings": true, "campaign_name": "SuperFuntime", "created_at": "2012-04-18T06:05:05Z", "updated_at": "2012-05-03T13:53:23Z", "greeting": { "message": "Hi there! Press one to continue.", "voice_gender": "Female", "audio_file_name": null, "audio_file_content_type": null, "audio_file_size": null, "audio_file_updated_at": null, "inherited": true }, "timers": [ { "timer": { "id": 113, "seconds": 0, "url": "https://track.example.com/click?cid=[campaign_id]&afid=[affiliate_id]", "dedupe_seconds": null, "type": null, "afid": null, "tid": null, "inherited": true } } ], "menu_options": [ { "menu_option": { "id": 44, "option": "1", "target_number": "+18667878878", "target_cid": null, "inherited": true } } ] } } ``` ### Top-level fields | Field | Type | Description | | ------------------------ | ----------------- | ---------------------------------------------------------------------------------------- | | `id` | integer | Retreaver's internal ID for the number. | | `number` | string | E.164 phone number assigned to this record. | | `country` | string | ISO 3166-1 alpha-2 country code (e.g. `US`, `CA`). | | `toll_free` | boolean | Whether the number is toll-free. | | `sid` | string \| null | SubID this number belongs to. | | `afid` | string \| null | Affiliate AFID this number belongs to. | | `cid` | string \| null | Campaign CID this number belongs to. | | `name` | string \| null | Optional label for the number. | | `uses_campaign_settings` | boolean \| null | `true` when greeting, timers, and menu options inherit from the campaign. | | `campaign_name` | string \| null | Name of the campaign this number belongs to. | | `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). | ### Greeting | Field | Type | Description | | -------------------------- | ----------------- | ------------------------------------------------------------------- | | `message` | string \| null | Text-to-speech greeting text. | | `voice_gender` | string \| null | `Male` or `Female`. | | `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. | | `inherited` | boolean | `true` when the greeting is inherited from the campaign. | ### Timer Each timer is wrapped under a `timer` root key in responses. | Field | Type | Description | | ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------- | | `id` | integer | Internal ID of the timer. | | `seconds` | integer | Minimum call duration before this timer fires. `0` fires at call start (click); `>0` is a sale threshold. | | `url` | string | URL fired 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 AFID this timer is scoped to. | | `tid` | string \| null | Target TID this timer is scoped to. | | `inherited` | boolean | `true` when the timer is inherited from the campaign. | ### Menu Option Each menu option is wrapped under a `menu_option` root key in responses. | Field | Type | Description | | --------------- | ---------------- | ---------------------------------------------------------------------------- | | `id` | integer | Internal ID of the menu option. | | `option` | string | DTMF key the caller presses (`0`–`9`, `*`, `#`). | | `target_number` | string \| null | Phone number to route the caller to. | | `target_cid` | string \| null | Campaign CID to route the caller to. Overrides `target_number` when set. | | `inherited` | boolean | `true` when the menu option is inherited from the campaign. | ## List all Numbers ```shell curl "https://api.retreaver.com/numbers.json?api_key=[api_key]&company_id=1" ``` > The above command returns an array of Number objects. Returns all Numbers for the authenticated Company. ### HTTP Request ```shell curl "https://api.retreaver.com/numbers.json?api_key=[api_key]&company_id=1" ``` ### Query Parameters | Parameter | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `client_cid` | string | Filter by campaign CID hash (e.g. `07c5f595`). Distinct from the numerical `campaign_id`. | | `client_afid` | string | Filter by affiliate AFID hash (e.g. `b687ad95`). Distinct from the numerical `affiliate_id`. | | `sub_id` | string | Filter by SubID. | | `page` | integer | Page of results to return. Defaults to `1`. | | `per_page` | integer | Results per page. Defaults to `25`, maximum `100`. | ## Get a specific Number ```shell curl "https://api.retreaver.com/numbers/5.json?api_key=[api_key]&company_id=1" ``` > The above command returns a single Number object. Returns a Number by its Retreaver internal ID. ### HTTP Request ```shell curl "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1" ``` ### Path Parameters | Parameter | Type | Description | | --------- | ------- | ------------------------------------- | | `id` | integer | Retreaver's internal ID of the number. | ## Create a Number ```shell curl -s \ -X POST \ "https://api.retreaver.com/numbers.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{ "number": { "type": "Toll-free", "afid": "0002", "cid": "abc123", "sid": "superaffiliate" } }' ``` > The above command returns the newly created Number object. Provisions a new phone number and assigns it to a Campaign and Affiliate. - The Campaign identified by `cid` must already exist. - If the Affiliate identified by `afid` does not exist, it is created automatically. - Greeting, timers, and menu options inherit from the Campaign unless explicitly overridden. **Greeting options (pick one):** - `message` + `voice_gender` — text-to-speech. - `message_file_b64_data` + `message_file_b64_filename` — submit an audio file inline as Base64. ### HTTP Request ```shell curl -X POST "https://api.retreaver.com/numbers.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" ``` ### Body Parameters All parameters must be nested under a `number` key. | Parameter | Type | Default | Required | Description | | ---------------------------- | ------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `type` | string | `Toll-free` | | `Toll-free` or `Local`. | | `country` | string | `US` | | For `Local` numbers only. 2-letter ISO country code. Supported: `US`, `CA`, `AT`, `BE`, `DK`, `FI`, `FR`, `GB`, `IE`, `IT`, `NL`, `PL`, `SE`. | | `desired_text` | string | | | Vanity word to search for in the number (e.g. `TEST`). Falls back to a random number if unavailable. | | `afid` | string | | required | Affiliate AFID. Created automatically if it does not exist. | | `cid` | string | | required | Campaign CID. The campaign must already exist. | | `sid` | string | | | SubID for this number. | | `message` | string | | | _Text-to-speech._ Greeting read to the caller. Instruct them to press `1` to continue. | | `voice_gender` | string | `Female` | | _Text-to-speech._ `Male` or `Female`. | | `message_file_b64_data` | string | | | _Audio file._ Base64-encoded audio. | | `message_file_b64_filename` | string | | | _Audio file._ Original filename (e.g. `greeting.flac`). Use the highest quality audio available. | | `repeat` | integer | `4` | | Number of times to repeat the greeting. | | `timers_attributes` | array | | | Overrides campaign timers — see [Timer attributes](#timer-attributes). Omit to inherit from the campaign. | | `menu_options_attributes` | array | | | Overrides campaign menu options — see [Menu option attributes](#menu-option-attributes). Omit to inherit. | | `destroy_nested` | boolean | `false` | | When `true`, destroys existing timers and menu options on this number before applying the submitted values. | #### Timer attributes Only include timers if you want to override the Campaign's timers. When overridden, `inherited` is set to `false` on the returned timers. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `seconds` | integer | required | `0` fires at call start (click timer). `>0` fires when the call reaches that duration (sale timer). | | `url` | string | required | URL fired when the timer triggers. Supports token interpolation. Cookies from the click timer are passed through. | #### Menu option attributes Only include menu options if you want to override the Campaign's menu options. When overridden, `inherited` is set to `false` on the returned menu options. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- | | `option` | string | required | DTMF key (`0`–`9`, `*`, `#`). For a direct forward without an IVR, use `1`. | | `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. | > [!TIP] > Create with a text-to-speech greeting and a single-option IVR: > ```json > { > "number": { > "type": "Toll-free", > "afid": "0002", > "cid": "abc123", > "message": "Hi there! Press one to continue.", > "voice_gender": "Female", > "menu_options_attributes": [ > { "option": "1", "target_number": "+18005559999" } > ] > } > } > ``` ## Update a Number ```shell curl -s \ -X PUT \ "https://api.retreaver.com/numbers/79.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{"number":{"afid":"0005"}}' ``` > The above command returns the updated Number object. Updates attributes on the Number. Only the fields you pass are changed — omitted fields remain untouched. - Pass `afid` or `cid` to reassign the Number to a different Affiliate or Campaign. - Pass `message` (or `message_file_b64_data`) to set a custom greeting. Pass a blank `message` to revert to the Campaign greeting. - Pass `timers_attributes` or `menu_options_attributes` to override Campaign settings at the Number level. - Set `destroy_nested: true` to delete all existing per-Number timers and menu options before applying new values. ### HTTP Request ```shell curl -X PUT "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" ``` ### Path Parameters | Parameter | Type | Description | | --------- | ------- | ------------------------------------- | | `id` | integer | Retreaver's internal ID of the number. | ### Body Parameters Accepts the same parameters as [Create a Number](#create-a-number), except `type`, `country`, and `desired_text` (which only apply at provision time). All parameters are optional on update. > [!TIP] > Override Campaign timers with a Number-specific set: > ```json > { > "number": { > "destroy_nested": true, > "timers_attributes": [ > { "seconds": 0, "url": "https://track.example.com/click" }, > { "seconds": 60, "url": "https://track.example.com/convert" } > ] > } > } > ``` ## Delete a Number ```shell curl -X DELETE "https://api.retreaver.com/numbers/79.json?api_key=[api_key]&company_id=1" ``` Deletes a Number. The underlying phone number is deprovisioned within 24 hours. Deleting a Number that belongs to a Number Pool returns `400` with `{"error": "This number belongs to a number pool and cannot be destroyed."}`. ### HTTP Request ```shell curl -X DELETE "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1" ``` > [!WARNING] > If you are porting a Number to another provider, do not delete it until the port is confirmed complete. Deleting a Number that is mid-port will fail the port.