NAV
cURL

Introduction

The Retreaver Core API can be used to automate core business processes, like changing where calls are routed, and many other features that would normally be accessed through our account portal.

If you're looking for information on tracking visitors and displaying phone numbers on your landing pages, please see our Retreaver.js library.

The API can be used to automate core business processes, but does not currently support all functionality.

Please note: We're currently working on a better, versioned replacement for this API. But don't worry, this API isn't going away.

Version

This is our unversioned API and for sake of clarity we'll refer to it henceforth as:

Retreaver Core API

Multi-format

The Retreaver Core API can be accessed by JSON or XML. Simply change the file extension and Content-Type header to match your preferences.

We recommend using JSON since XML is archaic, has high overhead, and is generally awful.

Format Content-Type Extension
JSON application/json json
XML text/xml xml

Nomenclature

Retreaver has gone through many revisions and currently uses two new sets of terms to refer to objects. Please note, this API uses our Old nomenclature.

Old Performance Marketing Edition Enterprise Edition
Affiliate Publisher Source
Target Buyer Contact Handler/Call Endpoint
Target Group Buyer Group Handler Group

Our IDs vs Customer IDs

For convenience, some objects can be accessed both by the IDs set by our customers and by our internal IDs.

Affiliates, Targets, and Campaigns can be accessed via customer editable IDs as "afid", "tid", and "cid" respectively.

The "id" property in the JSON/XML document refers to our internal ID.

Object Our Internal ID URL Customer Editable ID URL Customer Editable ID Accessor
Affiliate /affiliates/{id} /affiliates/afid/{afid} afid
Target /targets/{id} /targets/tid/{tid} tid
Campaign /campaigns/{id} /campaigns/cid/{cid} cid

These URLs work with GET, PUT, and DELETE HTTP verbs.

Please note, in many sections of the documentation below, we are referring to the Customer Editable ID URL.

Paginated

Retreaver is a RESTful paginated API that returns 25 results per page. Each relevant index response will have a Link HTTP header present.

Link: <https://retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=6996>; rel="last", <https://retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=2>; rel="next"

By parsing the Link header, you can determine the last, next, and previous pages.

Trees

Please note, for brevity, in appropriate places we have truncated the API output by eliminating properties of certain objects. We're also trying to save some trees in case someone actually tries to print this.

Authentication

To authorize, use this code:

# With cURL, you can just pass the correct API key and company_id with each request.
curl "https://api.retreaver.com/call.json?api_key=woofwoofwoof&company_id=1"

Make sure to replace woofwoofwoof with your API key.

Retreaver uses API keys to allow access to the API. You can register a new Retreaver Core API key at our account portal.

If you have a Retreaver account, you can find your Core API key at the bottom of your user page.

Retreaver expects for the API key to be included in all API requests to the server in a query string parameter that looks like the following:

?api_key=woofwoofwoof

If you have access to more than one company on Retreaver, you must also pass in the company ID of the company you want to work with:

?api_key=woofwoofwoof&company_id=1

You can find your company ID here. We suggest passing it in anyways.

If you suspect your API key has been publicly exposed, reset it.

Calls

Or, more precisely, phone calls.

Get recent Calls

curl "https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[{
   "call":{
      "uuid":"addcf985-017e-4962-be34-cf5d55e74afc",
      "caller":"+17195220377",
      "caller_zip":"80920",
      "caller_state":"CO",
      "caller_city":"COLORADO SPRINGS",
      "caller_country":"US",
      "dialed_call_duration":193,
      "total_duration":204,
      "status":"finished",
      "start_time":"2012-04-29T12:29:40Z",
      "forwarded_time":"2012-04-29T12:29:51Z",
      "end_time":"2012-04-29T12:32:46Z",
      "cid":"0003",
      "afid":"03994",
      "sid":null,
      "dialed_number":"+18668987878",
      "updated_at":"2012-04-29T12:29:46Z",
      "created_at":"2012-04-29T12:29:40Z",
      "recording_url":"http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
   }
},
{
   "call":{
      "uuid":"8ae0aa38-0173-4e62-5342-cf5d55e74afe",
      "caller":"+14166686981",
      "caller_zip":null,
      "caller_state":"ON",
      "caller_city":"TORONTO",
      "caller_country":"CA",
      "dialed_call_duration":33,
      "total_duration":40,
      "status":"finished",
      "start_time":"2012-04-29T12:29:40Z",
      "forwarded_time":"2012-04-29T12:29:51Z",
      "end_time":"2012-04-29T12:32:46Z",
      "cid":"0003",
      "afid":"03994",
      "sid":null,
      "dialed_number":"+18668987878",
      "updated_at":"2012-04-29T12:29:46Z",
      "created_at":"2012-04-29T12:29:40Z",
      "recording_url":"http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
   }
}]

Provides access to the call log. The call log contains all the Calls which have been made through Numbers under your control.

HTTP Request

GET https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1

Query Parameters

Parameter Default Description
created_at_start -4712-01-01T00:00:00+00:00 Return any Calls that were created after this date.
created_at_end 4712-01-01T00:00:00+00:00 Return any Calls that were created before this date.
order desc asc or desc, for ascending or descending.
sort_by created_at created_at or updated_at, Calls will be sorted by this value. If you only want recently updated Calls, sort by updated_at. Note that calls sorted by updated_at will forcefully be returned in desc order even if order parameter is asc.

Enumerate through all calls

First page...

curl "https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=1"

Second page...

curl "https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=2"

etc...

To fetch all Calls on your Account, use the sort_by and order params to return your Calls in the order they were created, and then paginate through all your calls.

HTTP Request

https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=1

https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=2

Enumerate through Calls in a specific date/time range.

curl "https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1"

By passing in created_at_start and created_at_end parameters, you can control the start and end time of Calls returned.

The timestamp should be formatted according to rfc3339

HTTP Request

GET https://api.retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1

Get a specific Call

curl "https://api.retreaver.com/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
   "call":{
      "uuid":"addcf985-017e-4962-be34-cf5d55e74afc",
      "caller":"+17195220377",
      "caller_zip":"80920",
      "caller_state":"CO",
      "caller_city":"COLORADO SPRINGS",
      "caller_country":"US",
      "dialed_call_duration":193,
      "total_duration":204,
      "status":"finished",
      "start_time":"2012-04-29T12:29:40Z",
      "forwarded_time":"2012-04-29T12:29:51Z",
      "end_time":"2012-04-29T12:32:46Z",
      "cid":"0003",
      "afid":"03994",
      "sid":null,
      "dialed_number":"+18668987878",
      "updated_at":"2012-04-29T12:29:46Z",
      "created_at":"2012-04-29T12:29:40Z",
      "recording_url":"http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
   }
}

Calls can be accessed by their UUID.

HTTP Request

GET https://api.retreaver.com/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=woofwoofwoof&company_id=1

Affiliates

Entering Affiliates into our system allows you to attribute calls back to the Affiliate who created them, and to update any external tracking systems.

If you're not in affiliate marketing, Affiliate objects can be used for whatever source attribution is relevant. Affiliates exist for your reference.

Get all Affiliates

curl "https://api.retreaver.com/affiliates.xml?api_key=woofwoofwoof&company_id=1"

The above command returns XML structured like this:

<?xml version="1.0" encoding="UTF-8"?>
<affiliates type="array">
  <affiliate>
    <afid>0002</afid>
    <first-name>Nancy</first-name>
    <last-name>Drew</last-name>
    <company-name>Acme</last-name>
    <updated-at type="datetime">2012-05-03T15:56:01Z</updated-at>
    <created-at type="datetime">2012-05-03T15:56:01Z</created-at>
  </affiliate>
</affiliates>

Provides a complete list of Affiliates.

HTTP Request

GET https://api.retreaver.com/affiliates.xml?api_key=woofwoofwoof&company_id=1

Get a specific Affiliate by your ID

curl "https://api.retreaver.com/affiliates/afid/0002.json?api_key=woofwoofwoof&company_id=1"

Finds an Affiliate by AFID.

HTTP Request

GET https://api.retreaver.com/affiliates/afid/0002.xml?api_key=woofwoofwoof&company_id=1

Create an Affiliate

curl -s \
    -X POST \
    https://api.retreaver.com/affiliates.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"affiliate":{"first_name":"Nancy", "last_name":"Drew", "afid":"0002"}}'

Creates an Affiliate.

HTTP Request

POST https://api.retreaver.com/affiliates.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"affiliate":{"first_name":"Nancy", "last_name":"Drew", "afid":"0002"}}

Parameters

Parameter Type Default Required Description
afid string null required The affiliate's ID. This should align with any external tracking systems you may be using.
first_name string null The affiliate's first name, for your reference.
last_name string null Their last name.
company_name string null Their company name.

Update an Affiliate

curl -s \
    -X PUT \
    https://api.retreaver.com/affiliates/afid/002.json \
    -H "Content-Type: application/json" \
    -d '{"affiliate":{"first_name":"Nathan"}}'

The above command returns JSON structured like this:

{
  "affiliate": {
    "afid": "002",
    "first_name": "Nathan",
    "last_name": "Drew",
    "company_name": null,
    "updated_at": "2012-05-03T20:20:03Z",
    "created_at": "2012-05-03T14:29:37Z"
  }
}

Changes any attributes you have passed in on the Affiliate.

HTTP Request

PUT https://api.retreaver.com/affiliates/afid/0002.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"affiliate":{"first_name":"Nathan"}}

Remove an affiliate

curl -X DELETE https://api.retreaver.com/affiliates/afid/0002.json?api_key=woofwoofwoof&company_id=1

Deletes the given Affiliate. You must delete any Numbers the Affiliate has before deleting the Affiliate.

Targets

Targets are the destination phone numbers that calls are routed to, for instance, your call center.

Get all Targets

curl "https://api.retreaver.com/targets.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[{
   "target": {
     "id": 6588,
     "number": "+18668987878",
     "sip_username": null,
     "sip_password": null,
     "cid_number_id": 10,
     "obfuscate_cid": false,
     "created_at": "2014-08-14T20:46:01.158-04:00",
     "updated_at": "2016-06-28T13:02:52.964-04:00",
     "object_key": "40a9a73ff97cb35a0a16d1ec89fd9eddcf3727df932cea9f0f7a5a8ba1684fed",
     "tid": null,
     "priority": 1,
     "weight": 1,
     "timeout_seconds": 15,
     "timer_offset": 0,
     "send_digits": null,
     "concurrency_cap": null,
     "calls_in_progress": 0,
     "inband_signals": false,
     "time_zone": "Eastern Time (US & Canada)",
     "paused": false,
     "paused_at": null,
     "name": "Jason Cell"
   }
}]

HTTP Request

GET https://api.retreaver.com/targets.json?api_key=woofwoofwoof&company_id=1

Get a specific Target

curl "https://api.retreaver.com/targets/6588.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
   "target": {
     "id": 6588,
     "number": "+18668987878",
     "sip_username": null,
     "sip_password": null,
     "cid_number_id": 10,
     "obfuscate_cid": false,
     "created_at": "2014-08-14T20:46:01.158-04:00",
     "updated_at": "2016-06-28T13:02:52.964-04:00",
     "object_key": "40a9a73ff97cb35a0a16d1ec89fd9eddcf3727df932cea9f0f7a5a8ba1684fed",
     "tid": null,
     "priority": 1,
     "weight": 1,
     "timeout_seconds": 15,
     "timer_offset": 0,
     "send_digits": null,
     "concurrency_cap": null,
     "calls_in_progress": 0,
     "inband_signals": false,
     "time_zone": "Eastern Time (US & Canada)",
     "paused": false,
     "paused_at": null,
     "name": "Jason Cell"
   }
}

HTTP Request

GET https://api.retreaver.com/targets/6588.json?api_key=woofwoofwoof&company_id=1

Create a Target

curl -s \
 -X POST \
 https://api.retreaver.com/targets.json?api_key=woofwoofwoof&company_id=1 \
 -H "Content-Type: application/json" \
 -d '{"target":{"number":"+18668987878", "name":"Retreaver Support"}}'

The above command returns JSON structured like this:

{
    "target": {
        "id": 22592,
        "number": "+18668987878",
        "sip_username": null,
        "sip_password": null,
        "cid_number_id": null,
        "obfuscate_cid": false,
        "created_at": "2016-06-28T23:13:51.434Z",
        "updated_at": "2016-06-28T23:13:51.434Z",
        "object_key": "97bbce7555b96322e81155eb4b1ff5aa9a6a1ffc478a7ab21ed2e830483f0b20",
        "tid": null,
        "priority": 1,
        "weight": 1,
        "timeout_seconds": 30,
        "timer_offset": 0,
        "send_digits": null,
        "concurrency_cap": null,
        "calls_in_progress": 0,
        "inband_signals": false,
        "time_zone": "UTC",
        "paused": false,
        "paused_at": null,
        "name": "Retreaver Support",
        "caps": [
            {
                "id": 707900,
                "filled": 0,
                "cap": null,
                "type": "Daily"
            },
            {
                "id": 707898,
                "filled": 0,
                "cap": null,
                "type": "Hard"
            },
            {
                "id": 707899,
                "filled": 0,
                "cap": null,
                "type": "Hourly"
            },
            {
                "id": 707901,
                "filled": 0,
                "cap": null,
                "type": "Monthly"
            }
        ],
        "business_hours": [
            {
                "id": 156838,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 0,
                "invert": false,
                "created_at": "2016-06-28T23:13:52.924Z",
                "updated_at": "2016-06-28T23:13:52.924Z"
            },
            {
                "id": 156839,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 1,
                "invert": false,
                "created_at": "2016-06-28T23:13:53.093Z",
                "updated_at": "2016-06-28T23:13:53.093Z"
            },
            {
                "id": 156840,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 2,
                "invert": false,
                "created_at": "2016-06-28T23:13:53.281Z",
                "updated_at": "2016-06-28T23:13:53.281Z"
            },
            {
                "id": 156841,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 3,
                "invert": false,
                "created_at": "2016-06-28T23:13:53.684Z",
                "updated_at": "2016-06-28T23:13:53.684Z"
            },
            {
                "id": 156842,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 4,
                "invert": false,
                "created_at": "2016-06-28T23:13:53.846Z",
                "updated_at": "2016-06-28T23:13:53.846Z"
            },
            {
                "id": 156843,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 5,
                "invert": false,
                "created_at": "2016-06-28T23:13:54.008Z",
                "updated_at": "2016-06-28T23:13:54.008Z"
            },
            {
                "id": 156844,
                "target_id": 22592,
                "work_day": true,
                "time_open": 0,
                "time_close": 2400,
                "day_of_week": 6,
                "invert": false,
                "created_at": "2016-06-28T23:13:54.165Z",
                "updated_at": "2016-06-28T23:13:54.165Z"
            }
        ],
        "tag_values": []
    }
}

Creates a new Target.

HTTP Request

POST https://api.retreaver.com/targets.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target":{"number":"+18668987878", "name":"Retreaver Support"}}

Parameters

Parameter Type Default Required Description
name string A descriptive moniker for this target so you'll know what it is.
number string required Either a phone number or sip:user@domain.com formatted SIP endpoint. PSTN numbers should be E.164 formatted.
sip_username string The SIP username, if using SIP-authentication to call a SIP endpoint.
sip_password string The SIP password, if using SIP-authentication to call a SIP endpoint.
tid string Your own internal ID for this target.
priority integer 1 The target with the lowest priority value gets considered first when routing calls to a set of targets.
weight integer 1 When more than one target has the same priority, the cumulative weight of the targets being considered is used to randomize their order.
timeout_seconds integer 30 The maximum number of seconds we'll wait while the target number is ringing before moving on.
inband_signals boolean false Enables detection of in-band ringing in conjunction with timer_offset.
timer_offset integer 0 Offsets any timers on Tracking URLs or Conversion Criteria when routing to this target. Can be used to simplify campaign management.
send_digits string Send these digits as DTMF tones when the call recipient picks up. Use w to make a 0.5 second pause. This can be used to bypass IVR systems.
concurrency_cap integer null Used to limit the maximum number of concurrent calls a target can receive.
paused boolean false Targets which are paused will not be considered when routing calls.
time_zone string UTC The time zone used when determining if a call is occuring during business hours.
business_hours_attributes array An optional array of business hours. Targets are set to be open 24/7 by default.

Nested Attribute: Business Hours

We'll only attempt to route calls to your target during its Business Hours. These hours are based on the Target time_zone. Note that when updating business hours on a Target, you must pass in the existing id attribute that gets created on this request.

Parameter Type Default Required Description
day_of_week integer required A zero-indexed day of the week, with 0 being Sunday and 6 being Saturday.
work_day boolean true Whether or not the target is open on this day.
time_open integer 0 The 24 hour time the target opens, formatted HHMM.
time_close integer 2400 The 24 hour time the target closes, formatted HHMM.
inverted boolean false Open hours become closed! Closed become open! Oh the insanity! Great if you have overnight shifts.

Valid Time Zones

Need to map IANA time zones to our format?

         
International Date Line West Midway Island American Samoa Hawaii Alaska
Pacific Time (US & Canada) Tijuana Mountain Time (US & Canada) Arizona Chihuahua
Mazatlan Central Time (US & Canada) Saskatchewan Guadalajara Mexico City
Monterrey Central America Eastern Time (US & Canada) Indiana (East) Bogota
Lima Quito Atlantic Time (Canada) Caracas La Paz
Santiago Newfoundland Brasilia Buenos Aires Montevideo
Georgetown Greenland Mid-Atlantic Azores Cape Verde Is.
Dublin Edinburgh Lisbon London Casablanca
Monrovia UTC Belgrade Bratislava Budapest
Ljubljana Prague Sarajevo Skopje Warsaw
Zagreb Brussels Copenhagen Madrid Paris
Amsterdam Berlin Bern Rome Stockholm
Vienna West Central Africa Bucharest Cairo Helsinki
Kyiv Riga Sofia Tallinn Vilnius
Athens Istanbul Minsk Jerusalem Harare
Pretoria Moscow St. Petersburg Volgograd Kuwait
Riyadh Nairobi Baghdad Tehran Abu Dhabi
Muscat Baku Tbilisi Yerevan Kabul
Ekaterinburg Islamabad Karachi Tashkent Chennai
Kolkata Mumbai New Delhi Kathmandu Astana
Dhaka Sri Jayawardenepura Almaty Novosibirsk Rangoon
Bangkok Hanoi Jakarta Krasnoyarsk Beijing
Chongqing Hong Kong Urumqi Kuala Lumpur Singapore
Taipei Perth Irkutsk Ulaanbaatar Seoul
Osaka Sapporo Tokyo Yakutsk Darwin
Adelaide Canberra Melbourne Sydney Brisbane
Hobart Vladivostok Guam Port Moresby Magadan
Solomon Is. New Caledonia Fiji Kamchatka Marshall Is.
Auckland Wellington Nuku'alofa Tokelau Is. Chatham Is.
Samoa

Update a Target

curl -s \
 -X PUT \
 https://api.retreaver.com/targets/22592.json \
 -H "Content-Type: application/json" \
 -d '{"target":{"paused":true}}'

The above command returns JSON structured like this:

{
    "target": {
        "id": 22592,
        "number": "+18668987878",
        "sip_username": null,
        "sip_password": null,
        "cid_number_id": null,
        "created_at": "2016-06-28T23:13:51.434Z",
        "updated_at": "2016-06-28T23:30:00.529Z",
        "paused": true,
        "paused_at": "2016-06-28T23:30:01.251Z",
        "name": "Retreaver Support"
    }
}

Changes any attributes you have passed in on the Target.

HTTP Request

PUT https://api.retreaver.com/targets/22592.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target":{"paused":true}}

Remove a Target

curl -X DELETE https://api.retreaver.com/targets/22592.json?api_key=woofwoofwoof&company_id=1

Deletes the given Target.

HTTP Request

DELETE https://api.retreaver.com/targets/22592.json?api_key=woofwoofwoof&company_id=1

Tagging a Target

curl -s \
 -X PUT \
 https://api.retreaver.com/targets/22592.json \
 -H "Content-Type: application/json" \
 -d '{"target":{"tag_list":"<<<calling_about:support>>>,<<<calling_about:other>>>"}}'

Upon reloading the Target, the following JSON is returned with the tags included:

{
    "target": {
        "id": 22592,
        "number": "+18668987878",
        "name": "Retreaver Support",
        "tag_values": [
            {
                "key": "calling_about",
                "value": "support",
                "operator": "==",
                "id": 67589
            },
            {
                "key": "calling_about",
                "value": "other",
                "operator": "==",
                "id": 67591
            }
        ]
    }
}

To set tags on a Target, pass in a comma delineated, triple-angle-bracket enclosed string of tags as the tag_list value.

The system will create/find whatever tags you have set given this input without you having to track tag IDs. You must include the full list of tags you want set any time a tag_list parameter is passed in. To clear the tags, just pass in a blank string.

There is a limit of 100 tags added in this manner, but the system will automatically concatenate US zip geo tags.

HTTP Request

PUT https://api.retreaver.com/targets/22592.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target":{"tag_list":"<<<calling_about:support>>>,<<<calling_about:other>>>"}}

Changing a Target's Caps

curl -s \
 -X PUT \
 https://api.retreaver.com/targets/22592.json \
 -H "Content-Type: application/json" \
 -d '{"target": { \
         "hard_cap_attributes": { \
             "cap": 100 \ 
             } \
         }' \
     }'

The above command returns JSON structured like this:

{
    "target": {
        "id": 22592,
        "number": "+18668987878",
        "name": "Retreaver Support",
        "caps": [
            {
                "id": 707900,
                "filled": 0,
                "cap": null,
                "type": "Daily"
            },
            {
                "id": 707898,
                "filled": 0,
                "cap": 100,
                "type": "Hard"
            },
            {
                "id": 707899,
                "filled": 0,
                "cap": null,
                "type": "Hourly"
            },
            {
                "id": 707901,
                "filled": 0,
                "cap": null,
                "type": "Monthly"
            }
        ]
    }
}

There are 4 types of caps: Hard Cap, Hourly Cap, Daily Cap, and Monthly Cap. Hard cap is a hard limit, and once it is reached, the target will not receive more Calls until the Cap is reset. This is useful when routing Calls to buyers that have insertion orders for a set number of leads.

The other types of Cap reset periodically as expected.

You can modify these Caps by updating your Target with nested objects hard_cap_attributes, hourly_cap_attributes, daily_cap_attributes, and monthly_cap_attributes.

HTTP Request

PUT https://api.retreaver.com/targets/22592.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target":{"hard_cap_attributes":{"cap":100}}}

Parameters

Parameter Type Default Required Description
cap integer required The value for the cap.

Resetting a Hard Cap

curl -s \
 -X POST \
 https://api.retreaver.com/targets/22592/reset_cap.json?api_key=woofwoofwoof&company_id=1 \
 -H "Content-Type: application/json"

Clears any Calls contributing to the given Target's hard cap, resetting it to 0. Returns HTTP 200 on success.

HTTP Request

POST https://api.retreaver.com/targets/22592/reset_cap.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

Campaigns

By configuring a Campaign, you can reuse the settings of the Campaign when creating Numbers. Campaigns should be configured before creating Numbers.

Get all Campaigns

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

The above command returns JSON structured like this:

[{
"campaign":{
   "cid":"111",
   "name":"SuperFuntime",
   "updated_at":"2012-07-15T03:40:24Z",
   "created_at":"2012-04-16T13:50:21Z",
   "record_calls":true,
   "record_seconds":3600,
   "dedupe_seconds":86400,
   "affiliate_can_pull_number":false,
   "show_key":"5e2ba674a8a1fb34dddcf850139ffdd9",
   "greeting":{
      "message":"Hi There! Press one to continue.",
      "voice_gender":"Female"
   },
   "timers":[
      {
         "timer":{
            "id":195,
            "seconds":0,
            "url":"http://www.thertrack.com/click.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]"
         }
      },
      {
         "timer":{
            "id":199,
            "seconds":90,
            "url":"http://www.thertrack.com/pixel.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]&MerchantReferenceID=[caller_id]-[called_number]-[call_duration]"
         }
      }
   ],
   "menu_options":[
      {
         "menu_option":{
            "id":61,
            "option":"1",
            "target_cid":null,
            "target_number":"+18987748833"
         }
      }
   ]
}
}]

List all the Campaigns in your Account.

HTTP Request

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

Get a specific Campaign

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

The above command returns JSON structured like this:

{
   "campaign":{
      "cid":"0044",
      "name":"SuperFuntime",
      "updated_at":"2012-07-15T03:40:24Z",
      "created_at":"2012-04-16T13:50:21Z",
      "record_calls":true,
      "record_seconds":3600,
      "dedupe_seconds":86400,
      "affiliate_can_pull_number":false,
      "show_key":"5e2ba674a8a1fb34dddcf850139ffdd9",
      "greeting":{
         "message":"Hi There! Press one to continue.",
         "voice_gender":"Female"
      },
      "timers":[
         {
            "timer":{
               "id":195,
               "seconds":0,
               "url":"http://www.thertrack.com/click.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]"
            }
         },
         {
            "timer":{
               "id":199,
               "seconds":90,
               "url":"http://www.thertrack.com/pixel.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]&MerchantReferenceID=[caller_id]-[called_number]-[call_duration]"
            }
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":61,
               "option":"1",
               "target_cid":null,
               "target_number":"+18987748833"
            }
         }
      ]
   }
}

Get a campaign by your ID.

HTTP Request

GET https://api.retreaver.com/campaigns/cid/0044.json?api_key=woofwoofwoof&company_id=1

Create a Campaign

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

The above command returns JSON structured like this:

{
   "campaign":{
      "cid":"0044",
      "name":"MyCampaign",
      "updated_at":"2012-07-15T03:34:00Z",
      "created_at":"2012-07-15T03:34:00Z",
      "record_calls":true,
      "record_seconds":3600,
      "dedupe_seconds":0,
      "affiliate_can_pull_number":false,
      "show_key":"5e2ba674a8a1fb34dddcf850139ffdd9",
      "greeting":{
         "message":"Thanks for calling, please press one to continue.",
         "voice_gender":"Male"
      },
      "timers":[
         {
            "timer":{
               "id":217,
               "seconds":0,
               "url":"http://callpixels.com/click.html"
            }
         },
         {
            "timer":{
               "id":218,
               "seconds":90,
               "url":"http://callpixels.com/sale.html"
            }
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":77,
               "option":"1",
               "target_cid":null,
               "target_number":"+16474570424"
            }
         }
      ]
   }
}

Create a new Campaign.

HTTP Request

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

Content-Type: application/json

{"campaign":{"cid":"0044","name":"MyCampaign","message":"Thanks for calling, please press one to continue.","voice_gender":"Male","timers_attributes":[{"seconds":0,"url":"http://callpixels.com/click.html"},{"seconds":90,"url":"http://callpixels.com/sale.html"}],"menu_options_attributes":[{"option":"1","target_number":"+16474570424"}]}}

Parameters

Parameter Type Default Required Description
cid string Random 8 characters Your internal campaign ID that will be referenced in the future.
name string A name for the campaign for your reference.
dedupe_seconds integer 0 (Disabled) Prevent a repeat caller from causing any Connect (timer.seconds == 0) or Sale (timer.seconds > 0) timer from firing within n seconds. Does not affect < 0 second timers.
affiliate_can_pull_number boolean false Allow affiliates to access this campaign via our LinkTrust integration.
record_calls boolean true Toggles call recording on and off.
message string Text-to-speech A message you want read aloud to the caller when they dial your number. Make sure to tell them to press one to continue.
voice_gender string Male Text-to-speech Male or Female, the gender of the text-to-speech voice you want.
message_file file Audio File An audio file you would like played for the caller when they dial your number. Use this field with multipart/form-data submissions.
message_file_b64_data string Audio File A Base64-encoded audio file. Only use this field if you're not using the message_file field.
message_file_b64_filename string Audio File The original file name for the Base64-encoded audio file. Something like 'memo.flac'. We suggest using the highest quality audio available.
repeat integer 4 The number of times to repeat the greeting.
timers_attributes array An array of timers.
menu_option_attributes array An array of menu options.
destroy_nested boolean false When set, causes existing timers and menu_options to be destroyed. Existing timers and menu options can be updated by including their unique ID. Alternatively, you can simply remove all the existing timers and menu options by setting this to true and resubmit all the values.

Nested Attribute: Timer

We will fire any 0 second timer ('click timer') before firing a sale timer (> 0 seconds). Only the highest second value sale timer that is applicable to this call will be fired. If you have timers for 30 seconds and 90 seconds and the call lasts 2 minutes, only the 90 second sale timer will be fired.

Parameter Type Default Required Description
seconds integer required The minimum length of time the call must last for this pixel to be fired. If set to 0, the pixel will fire at the beginning of the call, much like a click.
url string required The URL that should be called for this timer. The URL does not have to be a pixel, and will be passed any cookies that were set on the 0-second timer. Our bot follows redirects intelligently.

Nested Attribute: Menu Option

Menu options are used to route calls based on what button the caller presses on their phone. Menu options can redirect a caller to a different phone number or another CallPixels campaign. You must provide at least one menu option, and you must provide an option for '1', which is the option used to route calls when there is no greeting configured.

Parameter Type Default Required Description
option string required The button the caller will press. The default menu option for a campaign is the one for button press '1', so if you aren't using an IVR and want the call to forward instantly, set the option to '1'. (1 2 3 4 5 6 7 8 9 0 * #)
target_number string A phone number to redirect the caller to. All > 0 second timers will start when the call is answered.
target_cid string A campaign ID to redirect the caller to. The campaign must be configured in the system. If this value is set, it will overrride the target number. This option can be used to allow the caller to replay the greeting.

Update a Campaign

curl -s \
    -X PUT \
    https://api.retreaver.com/campaigns/cid/0044.json \
    -H "Content-Type: application/json" \
    -d '{"campaign":{"name":"My Other Campaign"}}'

The above command returns JSON structured like this:

{
   "campaign":{
      "cid":"0044",
      "name":"My Other Campaign",
      "updated_at":"2012-07-15T03:34:00Z",
      "created_at":"2012-07-15T03:34:00Z",
      "record_calls":true,
      "record_seconds":3600,
      "dedupe_seconds":0,
      "affiliate_can_pull_number":false,
      "show_key":"5e2ba674a8a1fb34dddcf850139ffdd9",
      "greeting":{
         "message":"Thanks for calling, please press one to continue.",
         "voice_gender":"Male"
      },
      "timers":[
         {
            "timer":{
               "id":217,
               "seconds":0,
               "url":"http://callpixels.com/click.html"
            }
         },
         {
            "timer":{
               "id":218,
               "seconds":90,
               "url":"http://callpixels.com/sale.html"
            }
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":77,
               "option":"1",
               "target_cid":null,
               "target_number":"+16474570424"
            }
         }
      ]
   }
}

Changes any attributes you have passed in on the Campaign.

HTTP Request

PUT https://api.retreaver.com/campaigns/cid/0044.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"affiliate":{"first_name":"Nathan"}}

Remove a Campaign

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

Delete a Campaign by CID. You must delete all the Numbers belonging to that Campaign first.

Numbers

Numbers are the physical phone numbers that you want routed to a Campaign. A Number can be routed directly to the Target phone number, or it can be screened with a greeting which requires the caller to press a button to continue. The IVR can be configured to have options that forward to other Campaigns if desired.

Numbers can be set to use the settings of an existing Campaign.

Get all Numbers

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

The above command returns JSON structured like this:

[{
    "number":{
       "id":5,
       "number":"+16479311232",
       "toll_free":false,
       "updated_at":"2012-05-03T13:53:23Z",
       "created_at":"2012-04-18T06:05:05Z",
       "sid":"superaffiliate",
       "afid":"0001",
       "cid":"111",
       "uses_campaign_settings":true,
       "greeting":{
          "message":"Hi There! Press one to continue.",
          "voice_gender":"Female",
          "inherited":true
       },
       "timers":[
          {
             "id":113,
             "seconds":0,
             "url":"http://www.thertrack.com/click.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]",
             "inherited":true
          },
          {
             "id":114,
             "seconds":5,
             "url":"http://www.thertrack.com/pixel.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]&MerchantReferenceID=[caller_id]-[called_number]-[call_duration]",
             "inherited":true
          }
       ],
       "menu_options":[
          {
             "menu_option":{
                "id":44,
                "option":"1",
                "target_cid":null,
                "target_number":"+18667878878",
                "inherited":true
             }
          }
       ]
    }
}]

Get all Numbers belonging to the Company.

HTTP Request

GET https://api.retreaver.com/numbers.json?api_key=woofwoofwoof&company_id=1

Parameters

Parameter Default Description
cid null Restrict results to Numbers that belong to the given Campaign ID.
afid null Restrict results to Numbers that belong to the given Affiliate ID.
sid null Restrict results to Numbers that belong to the given SubID.

Get a specific Number

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

The above command returns JSON structured like this:

{
   "number":{
      "id":5,
      "number":"+16479311232",
      "toll_free":false,
      "updated_at":"2012-05-03T13:53:23Z",
      "created_at":"2012-04-18T06:05:05Z",
      "sid":"superaffiliate",
      "afid":"0001",
      "cid":"111",
      "uses_campaign_settings":true,
      "greeting":{
         "message":"Hi There! Press one to continue.",
         "voice_gender":"Female",
         "inherited":true
      },
      "timers":[
         {
            "id":113,
            "seconds":0,
            "url":"http://www.thertrack.com/click.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]",
            "inherited":true
         },
         {
            "id":114,
            "seconds":5,
            "url":"http://www.thertrack.com/pixel.track?CID=[campaign_id]&AFID=[affiliate_id]&SID=[sub_id]&MerchantReferenceID=[caller_id]-[called_number]-[call_duration]",
            "inherited":true
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":44,
               "option":"1",
               "target_cid":null,
               "target_number":"+18667878878",
               "inherited":true
            }
         }
      ]
   }
}

Get a Number by our internal ID.

HTTP Request

GET https://api.retreaver.com/numbers/5.json?api_key=woofwoofwoof&company_id=1

Create a Number

curl -s \
    -X POST \
    https://api.retreaver.com/numbers.json \
    -H "Content-Type: application/json" \
    -d '{"number":{"type":"Toll-free","desired_text":"TEST","afid":"0002","cid":"0001","sid":"superaffiliate"}}'

The above command returns JSON structured like this:

{
   "number":{
      "id":79,
      "number":"+18008378206",
      "toll_free":true,
      "updated_at":"2012-07-15T03:15:42Z",
      "created_at":"2012-07-15T03:15:42Z",
      "sid":"superaffiliate",
      "afid":"0002",
      "cid":"0001",
      "uses_campaign_settings":true,
      "greeting":{
         "audio_file_name":"greeting.flac",
         "audio_file_content_type":"application/octet-stream",
         "audio_file_size":4990865,
         "audio_file_updated_at":"2012-07-15T01:30:34Z",
         "inherited":true
      },
      "timers":[
         {
            "timer":{
               "id":201,
               "seconds":0,
               "url":"http://callpixels.com.go2cloud.org/aff_c?offer_id=[campaign_id]&aff_id=[affiliate_id]&aff_sub=[sub_id]",
               "inherited":true
            }
         },
         {
            "timer":{
               "id":202,
               "seconds":90,
               "url":"http://callpixels.com.go2cloud.org/[has_offers_code]?adv_sub=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
               "inherited":true
            }
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":66,
               "option":"1",
               "target_cid":null,
               "target_number":"+18884899999",
               "inherited":true
            }
         },
         {
            "menu_option":{
               "id":71,
               "option":"2",
               "target_cid":"399944",
               "target_number":null,
               "inherited":true
            }
         }
      ]
   }
}

Creates a new phone Number.

HTTP Request

POST https://api.retreaver.com/numbers.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"number":{"type":"Toll-free","desired_text":"TEST","afid":"0002","cid":"0001","sid":"superaffiliate"}}

Parameters

Parameter Type Default Required Description
type string Toll-free required Toll-free or Local, the kind of number that is desired. Defaults to Toll-free.
desired_text string If you would like us to attempt to get a number that contains a specific word, enter it here. We will fall back to normal numbers if a number containing your word is not found.
country string US For Local numbers only, the 2 character country code for the country you would like the number to be in. Defaults to US. Possible values: US CA AT BE DK FI FR GB IE IT NL PL SE
afid string required The affiliate ID this number belongs to. If not found, we will create a new affiliate with this AFID.
cid string required The campaign ID this number belongs to. You must set up the campaign before creating a number for it.
sid string The SubID this number belongs to.
destroy_nested boolean false When set, causes existing timers and menu_options on this number to be destroyed.

Optional Parameters

Parameter Type Default Required Description
message string Text-to-speech A message you want read aloud to the caller when they dial your number. Make sure to tell them to press one to continue.
voice_gender string Male Text-to-speech Male or Female, the gender of the text-to-speech voice you want.
message_file file Audio File An audio file you would like played for the caller when they dial your number. Use this field with multipart/form-data submissions.
message_file_b64_data string Audio File A Base64-encoded audio file. Only use this field if you're not using the message_file field.
message_file_b64_filename string Audio File The original file name for the Base64-encoded audio file. Something like 'memo.flac'. We suggest using the highest quality audio available.
repeat integer 4 The number of times to repeat the greeting.
timers_attributes array An array of timers.
menu_options_attributes array An array of menu options.

Nested Attribute: Timer

Only include Timers if you want to override the Campaign settings. For more information on Timers, see Campaign.

If you do include Timers, the inherited attribute on them will be set to false.

Parameter Type Default Required Description
seconds integer required The minimum length of time the call must last for this pixel to be fired. If set to 0, the pixel will fire at the beginning of the call, much like a click.
url string required The URL that should be called for this timer. The URL does not have to be a pixel, and will be passed any cookies that were set on the 0-second timer. Our bot follows redirects intelligently.

Nested Attribute: Menu Option

Only include Menu Options if you want to override the Campaign settings. See Campaign for more details.

If you do include Menu Options, the inherited attribute on them will be set to false.

Parameter Type Default Required Description
option string required The button the caller will press. The default menu option for a campaign is the one for button press '1', so if you aren't using an IVR and want the call to forward instantly, set the option to '1'. (1 2 3 4 5 6 7 8 9 0 * #)
target_number string A phone number to redirect the caller to. All > 0 second timers will start when the call is answered.
target_cid string A campaign ID to redirect the caller to. The campaign must be configured in the system. If this value is set, it will overrride the target number. This option can be used to allow the caller to replay the greeting.

Update a Number

curl -s \
    -X PUT \
    https://api.retreaver.com/numbers/79.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"number":{"afid":"0005"}}'

The above command returns JSON structured like this:

{
   "number":{
      "id":79,
      "number":"+15558237206",
      "toll_free":true,
      "updated_at":"2012-07-15T03:15:42Z",
      "created_at":"2012-07-15T03:15:42Z",
      "sid":"superaffiliate",
      "afid":"0005",
      "cid":"0001",
      "uses_campaign_settings":true,
      "greeting":{
         "audio_file_name":"greeting.flac",
         "audio_file_content_type":"application/octet-stream",
         "audio_file_size":4990865,
         "audio_file_updated_at":"2012-07-15T01:30:34Z",
         "inherited":true
      },
      "timers":[
         {
            "timer":{
               "id":201,
               "seconds":0,
               "url":"http://callpixels.com.go2cloud.org/aff_c?offer_id=[campaign_id]&aff_id=[affiliate_id]&aff_sub=[sub_id]",
               "inherited":true
            }
         },
         {
            "timer":{
               "id":202,
               "seconds":90,
               "url":"http://callpixels.com.go2cloud.org/[has_offers_code]?adv_sub=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
               "inherited":true
            }
         }
      ],
      "menu_options":[
         {
            "menu_option":{
               "id":66,
               "option":"1",
               "target_cid":null,
               "target_number":"+18884899999",
               "inherited":true
            }
         },
         {
            "menu_option":{
               "id":71,
               "option":"2",
               "target_cid":"399944",
               "target_number":null,
               "inherited":true
            }
         }
      ]
   }
}

Updates the Number with any attributes you have passed in.

HTTP Request

PUT https://api.retreaver.com/numbers/79.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"number":{"afid":"0005"}}

Remove a Number

curl -X DELETE https://api.retreaver.com/numbers/79.json?api_key=woofwoofwoof&company_id=1

Deletes the given number. Numbers will be deprovisioned within 24 hours. Do not delete Numbers if you are porting them to another provider, until you have confirmed that the port has completed.

Number Pools

Number Pools are used to dynamically assign Numbers whenever a user visits your website. Number Pools are used in lieu of static Numbers when you want to track many different attributes.

Get all Number Pools

curl "https://api.retreaver.com/number_pools.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[{
     "number_pool": {
         "id": 1,
         "numbers_count": 0,
         "type": "Toll-free",
         "country": "CA",
         "max_pool_size": 10,
         "buffer_seconds": 0,
         "updated_at": "2013-04-25T16:16:51Z",
         "created_at": "2013-04-25T16:16:51Z",
         "google_analytics": false,
         "hide_embedded_access": false,
         "afid": "0001",
         "cid": "111",
         "reserve_size": 1
     }
 }]

Returns all the Number Pools you have in our system.

HTTP Request

GET https://api.retreaver.com/number_pools.json?api_key=woofwoofwoof&company_id=1

Parameters

Parameter Default Description
cid null Restrict results to Number Pools that belong to the given Campaign ID.
afid null Restrict results to Number Pools that belong to the given Affiliate ID.

Get a specific Number Pool

curl "https://api.retreaver.com/number_pools/1.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
    "number_pool": {
        "id": 1,
        "numbers_count": 0,
        "type": "Toll-free",
        "country": "CA",
        "max_pool_size": 10,
        "buffer_seconds": 0,
        "updated_at": "2013-04-25T16:16:51Z",
        "created_at": "2013-04-25T16:16:51Z",
        "google_analytics": false,
        "hide_embedded_access": false,
        "afid": "0001",
        "cid": "111",
        "reserve_size": 1
    }
}

Returns a single Number Pool based on our internal ID.

HTTP Request

GET https://api.retreaver.com/number_pools/1.json?api_key=woofwoofwoof&company_id=1

Create a Number Pool

curl -s \
    -X POST \
    https://api.retreaver.com/number_pools.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{ \
            "number_pool": { \
                "cid": "111", \
                "max_pool_size": 100, \           
                "hide_embedded_access": true, \
                "google_analytics": true \
            } \                             
        }'

The above command returns JSON structured like this:

{
    "number_pool": {
        "id": 49,
        "numbers_count": 0,
        "country": "US",
        "max_pool_size": 100,
        "buffer_seconds": 0,
        "updated_at": "2013-04-25T16:53:52Z",
        "created_at": "2013-04-25T16:53:52Z",
        "hide_embedded_access": true,
        "google_analytics": true,
        "afid": null,
        "cid": "111",
        "type": "Toll-free",
        "reserve_size": 1,
        "google_analytics_paths": [
            {
                "name": "Network timer (always)",
                "path": "/callpixels/8ddc04aa-0020-45eb-89df-ed45b8ed43a7"
            },
            {
                "name": "Network timer (connect)",
                "path": "/callpixels/18135f62-00ff-4818-941d-d88b6a93f27d"
            }
        ]
    }
}

Creates a new Number Pool.

HTTP Request

POST https://api.retreaver.com/number_pools.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"number_pool":{"cid":"111","max_pool_size":100,"hide_embedded_access":true,"google_analytics":true}}

Parameters

Parameter Type Default Required Description
cid string required The campaign ID this number pool belongs to. You must set up the campaign before creating a number pool for it.
type string Toll-free Toll-free or Local, the type of number that is desired for this number pool.
country string US For Local number pools only, the 2 character country code for the country you would like the numbers to be in. Possible values: US CA AT BE DK FI FR GB IE IT NL PL SE
afid string The affiliate ID this number pool belongs to. You must set up the affiliate before you create the number pool.
max_pool_size integer 10 The maximum number of numbers you want in this number pool.
buffer_seconds integer 0 The number of seconds for a number to retain its assignment after the visitor has left your site.
hide_embedded_access boolean false When true, will not show the embedded affiliate phone number management interface for this campaign.
google_analytics boolean false Enables our Google Analytics integration. Incompatible with number pools that have an assigned affiliate.
reserve_size integer 1 The number of numbers to pre-provision and hold in reserve. Allows numbers to be instantly assigned and helps avoid delays in provisioning numbers.

Update a Number Pool

curl -s \
    -X PUT \
    https://api.retreaver.com/number_pools/49.json \
    -H "Content-Type: application/json" \
    -d '{"number_pool":{"max_pool_size":"1000"}}'

The above command returns JSON structured like this:

{
    "number_pool": {
        "id": 49,
        "numbers_count": 0,
        "country": "US",
        "max_pool_size": 1000,
        "buffer_seconds": 0,
        "updated_at": "2013-04-25T18:53:52Z",
        "created_at": "2013-04-25T16:53:52Z",
        "hide_embedded_access": true,
        "google_analytics": true,
        "afid": null,
        "cid": "111",
        "type": "Toll-free",
        "reserve_size": 1,
        "google_analytics_paths": [
            {
                "name": "Network timer (always)",
                "path": "/callpixels/8ddc04aa-0020-45eb-89df-ed45b8ed43a7"
            },
            {
                "name": "Network timer (connect)",
                "path": "/callpixels/18135f62-00ff-4818-941d-d88b6a93f27d"
            }
        ]
    }
}

Updates the Number Pool with any attributes you have passed in.

HTTP Request

PUT https://api.retreaver.com/number_pools/49.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"number_pool":{"max_pool_size":"1000"}}

Remove a Number Pool

curl -X DELETE https://api.retreaver.com/number_pools/49.json?api_key=woofwoofwoof&company_id=1

Deletes the given Number Pool.

Companies

Company exists to allow resellers to separate their resources by Company. AFID and CID collisions will not occur between Companies.

Get the active Company

curl "https://api.retreaver.com/company.json?api_key=woofwoofwoof"

The above command returns JSON structured like this:

{
    "company": {
        "id": 1,
        "name": "CallPixels",
        "default_click_url": "http://callpixels.com/?a=[affiliate_id]&c=[campaign_id]&cp=js&s1=[sub_id]",
        "default_sale_url": "http://callpixels.com/p.ashx?o=[campaign_id]&t=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
        "created_at": "2012-04-15T05:44:10Z",
        "updated_at": "2012-05-07T15:32:44Z"
    }
}

Returns the currently active Company. This is the Company that will be modified if a request is sent in without a specific company_id.

HTTP Request

GET https://api.retreaver.com/company.json?api_key=woofwoofwoof

Get a specific Company

curl "https://api.retreaver.com/companies/1.json?api_key=woofwoofwoof"

The above command returns JSON structured like this:

{
    "company": {
        "id": 1,
        "name": "CallPixels",
        "default_click_url": "http://callpixels.com/?a=[affiliate_id]&c=[campaign_id]&cp=js&s1=[sub_id]",
        "default_sale_url": "http://callpixels.com/p.ashx?o=[campaign_id]&t=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
        "created_at": "2012-04-15T05:44:10Z",
        "updated_at": "2012-05-07T15:32:44Z"
    }
}

Returns the Company matching our internal ID.

HTTP Request

GET https://api.retreaver.com/companies/1.json?api_key=woofwoofwoof

Get all Companies

curl "https://api.retreaver.com/companies.json?api_key=woofwoofwoof"

The above command returns JSON structured like this:

[{
     "company": {
         "id": 1,
         "name": "CallPixels",
         "default_click_url": "http://callpixels.com/?a=[affiliate_id]&c=[campaign_id]&cp=js&s1=[sub_id]",
         "default_sale_url": "http://callpixels.com/p.ashx?o=[campaign_id]&t=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
         "created_at": "2012-04-15T05:44:10Z",
         "updated_at": "2012-05-07T15:32:44Z"
     }
 }]

Provides a complete list of Companies accessible via your Account.

HTTP Request

GET https://api.retreaver.com/companies.json?api_key=woofwoofwoof

Create a Company

curl -s \
    -X POST \
    https://api.retreaver.com/companies.json \
    -H "Content-Type: application/json" \
    -d '{"company":{"name":"CallPixels.com"}}'

The above command returns JSON structured like this:

{
     "company": {
         "id": 1,
         "name": "CallPixels",
         "default_click_url": "http://callpixels.com/?a=[affiliate_id]&c=[campaign_id]&cp=js&s1=[sub_id]",
         "default_sale_url": "http://callpixels.com/p.ashx?o=[campaign_id]&t=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
         "created_at": "2012-04-15T05:44:10Z",
         "updated_at": "2012-05-07T15:32:44Z"
     }
}

Creates a Company.

HTTP Request

POST https://api.retreaver.com/companies.json?api_key=woofwoofwoof

Content-Type: application/json

{"company":{"name":"CallPixels.com"}}

Parameters

Parameter Type Default Required Description
name string required The company name.
default_click_url string The default click URL to set as a Timer @ 0 seconds when creating a campaign.
default_sale_url string The default sale URL to set as a Timer @ 90 seconds when creating a campaign

Update a Company

curl -s \
    -X PUT \
    https://api.retreaver.com/companies/2.json \
    -H "Content-Type: application/json" \
    -d '{"company":{"name":"Retreaver"}}'

The above command returns JSON structured like this:

{
     "company": {
         "id": 2,
         "name": "Retreaver",
         "default_click_url": "http://callpixels.com/?a=[affiliate_id]&c=[campaign_id]&cp=js&s1=[sub_id]",
         "default_sale_url": "http://callpixels.com/p.ashx?o=[campaign_id]&t=[call_log_id]-[caller_id]-[called_number]-[call_duration]-[call_recording_url]",
         "created_at": "2012-04-15T05:44:10Z",
         "updated_at": "2012-05-07T15:32:44Z"
     }
}

Updates the given Company with any attributes you have passed in.

HTTP Request

PUT https://api.retreaver.com/companies/2.json?api_key=woofwoofwoof

Content-Type: application/json

{"company":{"name":"Retreaver"}}

Remove a Company

curl -X DELETE https://api.retreaver.com/companies/2.json?api_key=woofwoofwoof

Deletes the given Company. You must delete any Numbers and Number Pools the Company has first.

HTTP Request

DELETE https://api.retreaver.com/companies/2.json?api_key=woofwoofwoof

Contacts

Contacts allow you to tie individual Calls from many Contact Numbers back to one person. You can also tag Contacts, and calls from their Contact Numbers will automatically inherit the tags.

Get all Contacts

curl "https://api.retreaver.com/contacts.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18668987878",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Retreaver Support",
                "operator": "==",
                "id": 154060720
            }
        ]
    }
}]

Provides a complete list of Contacts.

HTTP Request

GET https://api.retreaver.com/contacts.json?api_key=woofwoofwoof&company_id=1

Get a Specific Contact by ID

curl "https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18668987878",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Retreaver Support",
                "operator": "==",
                "id": 154060720
            }
        ]
    }
}

Finds a Contact by its Retreaver ID.

HTTP Request

GET https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1

Create a Contact

curl -s \
    -X POST \
    https://api.retreaver.com/contacts.json \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}'

The above command returns JSON structured like this:

{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18668987878",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Retreaver Support",
                "operator": "==",
                "id": 154060720
            }
        ]
    }
}

Creates a Contact and associated Contact Number(s).

HTTP Request

POST https://api.retreaver.com/contacts.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}

Parameters

Parameter Type Default Required Description
tag_list string See notes below.
contact_numbers_attributes array required An array of Contact Numbers.

Nested Attribute: Contact Number

These are the phone numbers that are associated with your Contact.

Parameter Type Default Required Description
number string required Either a phone number or sip:user@domain.com formatted SIP endpoint. PSTN numbers should be E.164 formatted.
description string A description of the phone number, like 'Home', 'Mobile', 'Work', 'iPhone', etc.

tag_list notes

To set tags on a Contact, pass in a comma delineated, triple-angle-bracket enclosed string of tags as the tag_list value.

The system will create/find whatever tags you have set given this input without you having to track tag IDs. You must include the full list of tags you want set any time a tag_list parameter is passed in. To clear the tags, just pass in a blank string.

There is a limit of 100 tags added in this manner, but the system will automatically concatenate US zip geo tags.

Update a Contact

curl -s \
    -X PUT \
    https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}'

The above command returns JSON structured like this:

{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18001234567",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Retreaver Support",
                "operator": "==",
                "id": 154060720
            }
        ]
    }
}

Changes any attributes you have passed in on the Contact. To change a Contact Number, you must pass in the ID of the existing Contact Number, or see below for an easier method.

HTTP Request

PUT https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}

Remove a Contact

curl -X DELETE https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1

Deletes the given Contact and all Contact Numbers associated with it.

HTTP Request

DELETE https://api.retreaver.com/contacts/2.json?api_key=woofwoofwoof&company_id=1

Get a specific Contact by phone number

curl "https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18001234567",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Retreaver Support",
                "operator": "==",
                "id": 154060720
            }
        ]
    }
}

Finds a Contact by phone number.

HTTP Request

GET https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1

Update a Contact by phone number

curl -s \
    -X PUT \
    https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}'

The above command returns JSON structured like this:

{
    "contact": {
        "id": 2,
        "contact_numbers": [
            {
                "number": "+18001234567",
                "description": "Landline",
                "id": 2
            }
        ],
        "tag_values": [
            {
                "key": "name",
                "value": "Invalid Number",
                "operator": "==",
                "id": 154060721
            }
        ]
    }
}

Updates a Contact by phone number.

HTTP Request

PUT https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}

Delete a Contact by phone number

curl -X DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1

Deletes the contact associated with the phone number and all other contact numbers associated with the contact.

HTTP Request

DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=woofwoofwoof&company_id=1

Contact Numbers

A convenience API for removing and updating Contact Numbers.

Delete a Contact Number from a Contact by phone number

curl -X DELETE https://api.retreaver.com/contact_numbers/+18668987878.json?api_key=woofwoofwoof&company_id=1

Deletes the contact number from the Contact it is associated with, as long as the Contact has more than one Contact Number.

HTTP Request

DELETE https://api.retreaver.com/contact_numbers/+18668987878.json?api_key=woofwoofwoof&company_id=1

Update a Contact Number by phone number

curl -s \
    -X PUT \
    https://api.retreaver.com/contact_numbers/+18001234567.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact_number":{"number":"+18005551234"}}'

The above command returns JSON structured like this:

{
    "contact_number": {
        "number": "+18005551234",
        "description": "Landline",
        "id": 2
    }
}

Easily updates a Contact Number.

HTTP Request

PUT https://api.retreaver.com/contact_numbers/+18001234567.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"contact_number":{"number":"+18005551234"}}

Suppressed Numbers

Check and modify whether or not a Contact Number is blocked by your Suppression List.

Check whether or not you have any Suppressed Numbers

curl https://api.retreaver.com/suppression_list/check.json?api_key=woofwoofwoof&company_id=1

The above command returns JSON structured like this:

{"suppression_list":true}

Returns true if the Company has any numbers suppressed.

HTTP Request

GET https://api.retreaver.com/suppression_list/check.json?api_key=woofwoofwoof&company_id=1

Delete a Contact Number from the Suppression List by phone number

curl -X DELETE https://api.retreaver.com/contact_numbers/+18668987878/suppressed_number.json?api_key=woofwoofwoof&company_id=1

Removes the Contact Number from your Suppression List.

HTTP Request

DELETE https://api.retreaver.com/contact_numbers/+18668987878/suppressed_number.json?api_key=woofwoofwoof&company_id=1

Suppress a Contact Number by phone number

curl -s \
    -X POST \
    https://api.retreaver.com/contact_numbers/+18668987878/suppressed_number.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"suppressed_number":{"can_resubscribe":false}}'

The above command returns JSON structured like this:

{
    "suppressed_number": {
        "id": 502997,
        "number": "+18668987878",
        "can_resubscribe": false,
        "created_at": "2013-10-02T14:36:14.166-04:00"
    }
}

Adds a Contact Number to the Company's Suppression List. The can_resubscribe value toggles whether or not the contact can unblock themselves by pressing 7 if there is a "Caller Blocked" Prompt on the Campaign/Number they are calling.

The entire body of the post is optional, simply posting to https://api.retreaver.com/contact_numbers/+18668987878/suppressed_number.json?api_key=woofwoofwoof&company_id=1 would block +18668987878; can_resubscribe is true by default. The intended use case is to allow callers to restore contact with a company after choosing to be routed to a "add caller to suppression list and hang up" routing option.

HTTP Request

POST https://api.retreaver.com/contact_numbers/+18668987878/suppressed_number.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"suppressed_number":{"can_resubscribe":false}}

Static Caller Numbers

Static Caller Numbers are used to tell Retreaver that calls from a certain CallerID should be handled separately. Use Static Caller Numbers when you have a call center sending you many calls with the same CallerID. Retreaver will either prompt the caller for the caller's real number, or will randomize the CallerID for use with our call control API.

Get all Static Caller Numbers

curl "https://api.retreaver.com/static_caller_numbers.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[{
    "static_caller_number": {
        "id": 1234,
        "number": "+18668987878",
        "created_at": "2013-10-02T14:36:14.166-04:00"
    }
}]

Provides a complete list of Static Numbers.

HTTP Request

GET https://api.retreaver.com/static_caller_numbers.json?api_key=woofwoofwoof&company_id=1

Create a Static Caller Number

curl -s \
    -X POST \
    https://api.retreaver.com/static_caller_numbers.json?api_key=woofwoofwoof&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"static_caller_number":{"number":"+18668987878"}}'

Creates a Static Caller Number.

HTTP Request

POST https://api.retreaver.com/static_caller_numbers.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"static_caller_number":{"number":"+18668987878"}}

Parameters

Parameter Type Default Required Description
number string null required A phone number in E.164 format.

Delete a Static Caller Number

curl -X DELETE https://api.retreaver.com/static_caller_numbers/1234.json?api_key=woofwoofwoof&company_id=1

Removes the Static Caller Number.

HTTP Request

DELETE https://api.retreaver.com/static_caller_numbers/1234.json?api_key=woofwoofwoof&company_id=1

Target Groups

Target Groups group Target objects and can be used in Campaign/Number routing settings, allowing you to easily manage how calls are routed.

Get all Target Groups

curl "https://api.retreaver.com/target_groups.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

[
  {
    "target_group": {
      "id": 1,
      "name": "test",
      "target_ids": [
        1,
        2,
        3
      ],
      "concurrency_cap": null,
      "calls_in_progress": 0,
      "behavior": 1,
      "priority": null,
      "weight": null,
      "caps": [
        {
          "id": 652980,
          "filled": 0,
          "cap": null,
          "type": "Daily"
        },
        {
          "id": 652978,
          "filled": 0,
          "cap": null,
          "type": "Hard"
        },
        {
          "id": 652979,
          "filled": 0,
          "cap": null,
          "type": "Hourly"
        },
        {
          "id": 652981,
          "filled": 0,
          "cap": null,
          "type": "Monthly"
        }
      ]
    }
  }
]

HTTP Request

GET https://api.retreaver.com/target_groups.json?api_key=woofwoofwoof&company_id=1

Get a specific Target Group

curl "https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1"

The above command returns JSON structured like this:

{
  "target_group": {
    "id": 1,
    "name": "test",
    "target_ids": [
      1,
      2,
      3
    ],
    "concurrency_cap": null,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

HTTP Request

GET https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Create a Target Group

curl -s \
 -X POST \
 https://api.retreaver.com/target_groups.json?api_key=woofwoofwoof&company_id=1 \
 -H "Content-Type: application/json" \
 -d '{"target_group":{"target_ids": [1, 2, 3], "name":"test", "concurrency_cap": 5}}'

The above command returns JSON structured like this:

{
  "target_group": {
    "id": 1,
    "name": "test",
    "target_ids": [
      1,
      2,
      3
    ],
    "concurrency_cap": 5,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

Creates a new Target Group.

HTTP Request

POST https://api.retreaver.com/target_groups.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"target_ids": [1, 2, 3], "name":"test", "concurrency_cap": 5}}

Parameters

Parameter Type Default Required Description
name string required A descriptive moniker for this target group so you'll know what it is.
priority integer null if behavior = 2 Used to set the priority of the group when dialing using simuldial. See Target documentation for more information.
weight integer null if behavior = 2 Used to set the weight of the group when dialing using simuldial. See Target documentation for more information.
concurrency_cap integer null Used to limit the maximum number of concurrent calls this target group can receive.
target_ids integer array [ ] A list of target IDs that will belong to this group.
behavior integer 1 1 = Dial separately, 2 = Simuldial (dial all Targets within the group at the same time)

Update a Target Group

curl -s \
 -X PUT \
 https://api.retreaver.com/target_groups/1.json \
 -H "Content-Type: application/json" \
 -d '{"target_group":{"name":"hello"}}'

The above command returns JSON structured like this:

{
  "target_group": {
    "id": 1,
    "name": "hello",
    "target_ids": [
      1,
      2,
      3
    ],
    "concurrency_cap": 5,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

Changes any attributes you have passed in on the Target Group.

HTTP Request

PUT https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"name":"hello"}}

Delete a Target Group

curl -X DELETE https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Deletes the given Target Group.

HTTP Request

DELETE https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Replacing Targets in a Target Group

curl -s \
 -X PUT \
 https://api.retreaver.com/target_groups/1.json \
 -H "Content-Type: application/json" \
 -d '{"target_group":{"target_ids":[5,6]}}'

Upon reloading the Target, the following JSON is returned with the given targets:

{
  "target_group": {
    "id": 1,
    "name": "hello",
    "target_ids": [
      5,
      6
    ],
    "concurrency_cap": 5,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

To replace which Targets are in a Target Group, pass in an array of Target IDs as target_ids. All existing Targets on the Target Group will be replaced with the Targets provided in this array.

This is the standard method of updating the Target ID list in which you have to pass in the entire list each time. We also have 2 helper methods, below, for adding and removing Targets.

HTTP Request

PUT https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"target_ids":[5,6]}}

Adding Targets to a Target Group

curl -s \
 -X PUT \
 https://api.retreaver.com/target_groups/1.json \
 -H "Content-Type: application/json" \
 -d '{"target_group":{"add_targets_by_id":[4]}}'

Upon reloading the Target, the following JSON is returned with Target ID 4 added:

{
  "target_group": {
    "id": 1,
    "name": "hello",
    "target_ids": [
      1,
      2,
      3,
      4
    ],
    "concurrency_cap": 5,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

To add Targets to a Target Group, pass in an array of Target IDs as add_targets_by_id. This is a helper attribute provided so that you don't have to track which Targets are in each Group.

HTTP Request

PUT https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"add_targets_by_id":[4]}}

Removing Targets from a Target Group

curl -s \
 -X PUT \
 https://api.retreaver.com/target_groups/1.json \
 -H "Content-Type: application/json" \
 -d '{"target_group":{"remove_targets_by_id":[1]}}'

Upon reloading the Target, the following JSON is returned with Target ID 1 removed:

{
  "target_group": {
    "id": 1,
    "name": "hello",
    "target_ids": [
      2,
      3
    ],
    "concurrency_cap": 5,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": null,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

To remove Targets from a Target Group, pass in an array of Target IDs as remove_targets_by_id. This is a helper attribute provided so that you don't have to track which Targets are in each Group.

HTTP Request

PUT https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"remove_targets_by_id":[1]}}

Changing a Target Group's Caps

curl -s \
 -X PUT \
 https://api.retreaver.com/target_groups/1.json \
 -H "Content-Type: application/json" \
 -d '{"target_group": { \
         "hard_cap_attributes": { \
             "cap": 100 \ 
             } \
         }' \
     }'

The above command returns JSON structured like this:

{
  "target_group": {
    "id": 1,
    "name": "test",
    "target_ids": [
      1,
      2,
      3
    ],
    "concurrency_cap": null,
    "calls_in_progress": 0,
    "behavior": 1,
    "priority": null,
    "weight": null,
    "caps": [
      {
        "id": 652980,
        "filled": 0,
        "cap": null,
        "type": "Daily"
      },
      {
        "id": 652978,
        "filled": 0,
        "cap": 100,
        "type": "Hard"
      },
      {
        "id": 652979,
        "filled": 0,
        "cap": null,
        "type": "Hourly"
      },
      {
        "id": 652981,
        "filled": 0,
        "cap": null,
        "type": "Monthly"
      }
    ]
  }
}

There are 4 types of caps: Hard Cap, Hourly Cap, Daily Cap, and Monthly Cap. Hard cap is a hard limit, and once it is reached, Targets in the Target Group will not receive more Calls until the Cap is reset. This is useful when routing Calls to buyers that have insertion orders for a set number of leads.

The other types of Cap reset periodically as expected.

You can modify these Caps by updating your Target Group with nested objects hard_cap_attributes, hourly_cap_attributes, daily_cap_attributes, and monthly_cap_attributes.

HTTP Request

PUT https://api.retreaver.com/target_groups/1.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

{"target_group":{"hard_cap_attributes":{"cap":100}}}

Parameters

Parameter Type Default Required Description
cap integer required The value for the cap.

Resetting all Hard Caps on Targets in a Target Group

curl -s \
 -X POST \
 https://api.retreaver.com/target_groups/1/reset_cap.json?api_key=woofwoofwoof&company_id=1 \
 -H "Content-Type: application/json"

Clears any Calls contributing to the given Target Group's hard cap, resetting hard caps of all Targets within the Group to 0. Returns HTTP 200 on success.

HTTP Request

POST https://api.retreaver.com/target_groups/1/reset_cap.json?api_key=woofwoofwoof&company_id=1

Content-Type: application/json

Errors

The Retreaver Core API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request was unintelligible. Check your formatting.
401 Unauthorized -- Your API key is wrong or missing.
403 Forbidden -- You didn't pass in your Company ID or you're using the wrong API key.
404 Not Found -- It actually, really doesn't exist.
405 Method Not Allowed -- It doesn't respond to the HTTP action you used.
406 Not Acceptable -- You requested a format that isn't JSON, or, sigh, XML.
410 Gone -- It up and left or was otherwise deleted.
418 I'm a little teapot!
429 Too Many Requests -- Slow down. Highly concurrent requests are frowned upon.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.