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:

{
  "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

Greeting

Timer

Each timer is wrapped under a timer root key in responses.

Menu Option

Each menu option is wrapped under a menu_option root key in responses.

List all Numbers

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

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

Query Parameters

Get a specific Number

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

curl "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1"

Path Parameters

Create a Number

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

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.

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.

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.

{
  "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

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

curl -X PUT "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Path Parameters

Body Parameters

Accepts the same parameters as Create a Number, except type, country, and desired_text (which only apply at provision time). All parameters are optional on update.

{
  "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

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

curl -X DELETE "https://api.retreaver.com/numbers/{id}.json?api_key=[api_key]&company_id=1"