Number Pools

September 13, 2016 | Angela Dougherty

You will need a Number Pool configured for your campaign if you want numbers dynamically generated on the landing page for your caller data to uniquely be attributed to calls. Because we are tagging numbers dynamically as visitors reach your landing page, you might need a large number pool depending on the number of unique keyword/ad combinations that you want to track, but limited to the number of concurrent visitors you expect.

Once the visitor calls the number that is displayed, we automatically tag the call with any tags that have been set on the number.

You will need to use one of Retreaver’s two available scripts in your landing page.Our more robust Retreaver.js is our JavaScript library for displaying trackable phone numbers. It offers a flexible API so developers can interact with our services in a way that is both straightforward and compliant with modern standards. It is able to be cached by the visitors browser, and quickly distributed via a CDN.

More on Retreaver.js

If you run low volume traffic and do not require alerts, our much simpler Insert.js will fulfill your needs.

More on Insert.js

Creating a Number Pool

Click on Number Pools / New Number Pool or click here. Basically you have two ways of pulling numbers, ones you pull by doing Number/ New Number, and then ones we generate at the landing page using the Number Pools. The Sniffing Parameters you tell us to look for from the URL are put into Retreaver Tags and attributed to calls.

We ping from your site to Retreaver to know when a consumer is looking at a number. The Buffer Seconds dictates that after they leave, how much longer we hold onto the number/extension. The Max Lease Time dictates how long we let them view it it without calling before we release the number/extension back into the pool. Also once a call is ended, if there are no other users calling the same number, it is released back into to the pool.

A new visitor will reset the timer on the Max Lease Time, but once the Max Lease Time or the last visitor leaves, the number becomes available to be something else later.

Default Number

You need a default number in the source code in order to display to viewers as a fallback when your Number Pool is full. This Default Number is there work alongside the Number Pool. You would add a sub_id Tag for this Number and have it equal ‘default number’ so you know what this number is for in the future. It will be used when the number pool is not sized properly and we need to show a static number from our system. You lose tracking information about why the lander was called, but you won’t lose the call.

Default Sniffing Parameters

To configure your default Retreaver.js URL parameter sniffing settings you have to tell Retreaver what to look for in the URL.These defaults will make setting up new campaigns much quicker, especially if you have multiple levels of sub-affiliates to deal with. To edit your company settings, click Settings, then Company and select Edit at the top.

Default Parameter Sniffing settings.

Once you’ve opened the edit screen, you can choose what keywords to sniff out of the URL and what Tag name you want it to be assigned. In the example below, f_n is being assigned first_name in Retreaver.


Adding a URL parameter to sniff for in Company settings.

How Many Numbers do I Need?

This depends on how deeply you plan to track. You may primarily want to just track back to AffID and SubID. If tracking down to the ClickID, you will need one number displayed per page viewer, which can add up fast. This sort of granularity might be worth the cost in a large pool of numbers. However, if possible, if you can track to fewer keywords then you can ensure your pools will be smaller.

Example 1: If you are only tracking kw=test and 50,000 people are all looking at that keyword, they all get the same number. However if each browser has a different &kw= they will all get a different number. If all kinds of visitors have the same zoneid, they all see the same number. No reason to generate a new number per visitor if you are only tracking that field and it is the same for many visitors.

Example 2: If you send URL Source and SubSource, and in this example you only had 3 sources and 10 subsources, that is only a total combination of 30. So your Number Pool only needs 30 numbers and will track with 100% accuracy.

Example 3: 1 million visitors are viewing a web page and the URL reads This results in 1 million viewers all seeing the same number, since they share all the same tracking data.

In summary, it just depends on how long you set the Max Lease Time in the pool and what you are tracking. If you are tracking down to ClickID, it will be a unique number per visitor, that is how many concurrent visitors you have within the lease time. Try setting the Max Pool Size you think will work and then if we contact you via email saying that your pool is too small, you can either:

1) Ignore it and lose a bit of tracking details.


2) Increase the pool size to track what you want more accurately.

Filter Calls by Zip Code

May 26, 2016 | Angela Dougherty

Getting Started

Calls are automatically tagged with geo tags picked up from the caller ID, which can be added to your buyers to filter your calls. The geo tags that were picked up from the caller ID resolve information such as country, state and city.

However, if you require more granular filtering to be done with Zip codes, you will need to complete these two steps:

1) Add an IVR prompt for Zip codes in your Campaign settings under Prompts.


2) Add Tags to your buyer to filter what Zip codes they are able to take.

1) Creating Zip Code Entry Prompts

Zip code Entry

This prompt will play immediately when the call connects.

Zip entry

Creating a zip code entry prompt.

Zip Entry Failed

This plays when the caller does not enter a valid Zip code.

You will want this message to repeat a couple times.

zip failed

Creating a zip entry failed prompt.

Filtering Calls to the Buyer Using Tags

Tags on a buyer control what calls it can take.

More info on filtering calls to your buyers.

Edit the buyer, and add the appropriate geo tags to ensure that the buyer only receives calls from the designated geographical areas.

To add the tags, click on Wizard>Geo>Zip. From here you can enter zip codes individually or ideally, upload a file. This will tell Retreaver that these are the Zip codes this buyer can take, do not send this buyer calls from other Zip codes. It is worth noting that this Upload option will not accept Excel files, only CSV (comma separated values)

Tag Format

Geo tags are in the formatgeo:[ISO 3166-1 alpha-2 country code](-optional state, province or zip). For instance, the tag for California is geo:us-ca while the tag for Canada is geo:ca. For a Zip code 90210, the tag would be geo:us-90210.

How a Call gets Tagged

February 22, 2016 | Angela Dougherty

For the basics on how Retreaver’s Tags function, take a look at this article:

Introduction to Tag Types and Operators

All our reporting is simply based off what Tags are in the call_uuid for each individual call. This article will go over the five ways to get the call tagged with data:

1) Attached to static Numbers.

Pull a static number and add a Tag using the Tag Wizard. You could have a Tag like sub_id or custom Tags you’ve already created such as traffic_type:==online_listings. This is also where you would add a Buyer Tag to identify the Buyer(s) you want to force the call to.


New Number tagged with traffic_type and forcing calls to buyer_id:==16140.

2) At the landing page using our Script.

In this situation you define a Number Pool or an Extensions Pool. Based on what you tell us to sniff out of the URL and what Tags to put them in, we will either reuse a number if we find one in the pool that already has those Tags or we recycle a number if it has been returned to the pool. If you were only tracking affiliate_id and sub_id all viewers of the page would all see the same number.

Lastly, we create a new number on the fly to the max size of the pool. If you have defined your pool in such a way that it is too small for us to get a new number, then the default number is shown to the consumer.  This default number is usually another number in Retreaver that will not be able to track, but at least you won’t lose the call.

3) From Tags that prompt the caller to input an answer.

If the number has already been tagged with it, our system will skip asking those prompts since we already have the answer.

4) Outbound dial to the consumer from our system.

You only need one number per campaign for outbound dials, as you are Tagging the outbound call with the values you want on the call. In this situation only one number per campaign is needed, because you send the Tags on the outbound call to the consumer in the script that initiates the call, any values you send will be appended to the Tags already in the number or overwrite those Tags if they are the same.

5) Via Postback from a 3rd party tracking system.

You can send information to a 3rd part tracking system with the call_uuid and a call key. We can post to a data append company or even to your system with a caller id, the call uuid, and the call key, and they can send all kinds of information back to the call as it is happening or after the call is complete. Such as name, address, credit rating, or whatever you need.

Here is an example of a call in Retreaver that is being Tagged with the following values from all five ways a call can be attributed:


How Tags from many sources attribute the call with information.


How to filter calls to Buyers based on Tags

Routing to SIP and using SIP Headers

February 20, 2016 | Angela Dougherty

Routing Calls Via SIP Address

With Retreaver, you can route calls to SIP addresses and receive inbound calls via SIP.


Outbound SIP is done simply by changing the Buyer Phone Number to begin with sip: Once you begin typing this, the screen will change so that you can key in fields required to do outbound SIP. There are no changes needed to the Retreaver system to do outbound SIP, but it is important to know how the buyer will authenticate the calls via SIP to their system.

You may authenticate one of 3 ways

1) No authentication. (Just leave Username and Password Blank in Buyer Setup)
2) With Username and password.
3) By WhiteListing Twilio IP addresses. (Also leave Username and Password blank for this option)

For option 3, here is what your Buyer will need to know:

Signalling IPs to Whitelist

Port 5060 (UDP/TCP), 5061 (TLS)


In order to do inbound SIP to Retreaver, it will need to be set up manually so contact us at to get started.
Once you have those settings completed, you can begin setting up the inbound SIP.

For Inbound SIP, we require SIP authentication in one of 2 ways:

1) With Username and Password.
We give this to you during setup.
Example format:

2) By White Listing IP addresses where traffic will come from.
Send any lists from any source you need whitelisted to
Example format:
Any number you pull from the system can receive calls via SIP from any country. Just replace the +18882223333 with the phone number you want SIP calls to come in on. Don’t forget the country code!

Using SIP Headers

Calls to SIP-based Buyers automatically include several SIP headers in the INVITE request to the Buyer. These headers include X-PH-RetreaverUUID, the UUID for the call; X-PH-RetreaverKey, the postback key for the call; X-PH-RetreaverAFID, the publisher ID of the responsible Publisher; and X-PH-RetreaverSID, the sub_id of the responsible sub-affiliate if one is set.

Tag Types and Operators

February 12, 2016 | Angela Dougherty

Using the Tag Wizard

Use Retreaver’s simple Tag Wizard for easily managing the Tags on your Buyers, Numbers, Conversion Groups, and Tracking URLs.

Adding Tags

Click the Wizard icon next to any Tag input field to get started.

Step 1: Navigate to the relevant type, and select the Tag Key you want to use.

Step 2: Now we select the relevant operators for the type of tag you’re adding.

Step 3: Enter a value. We’ll compare the value on a call to this value using the operator you selected. If the call conforms to the resulting expression, we’ll call it a match.

Step 4: Click Add.

Step 5: Click Done.


Steps to creating a Tag.

Note: Your settings will not be active or saved until you save the underlying Buyer, Campaign, or Number.

You’ll notice two different colored dots on Tags. A blue dot means the Tag has just been added to the object. A red dot means the Tag has just been added to the object and has not been used in your Retreaver account before. Use these dots to keep track of what you’ve changed.

Tag Types


Different types of Tags.

This variety of Tag types should make it easy to track and route calls based on time and numerical values.

Now you can track and route calls based on your caller’s credit rating or date of birth.

Possible uses of date tags include:

  • Sale date for a mortgage.
  • Date of birth for insurance.
  • Graduation date for education.

Possible uses of numeric tags include:

  • Sale price for home mortgage.
  • Credit rating for loans.
  • Purchase price for auto.

Click here to learn to filter calls to Buyers based on Tags

Tag Operators

Use tags with operators to more selectively control which Buyers get routed to, which conversion group is used, or which tracking URLs are fired.

Available Operators


You can now use matching operators =~ and !~ on text tags to test for the presence or absence of a string or regular expression. Also available is the exclusion or not equal to operator, allowing you to block calls with certain attributes.

== [default]
Equals. The value on the call is exactly this value.

Not equal to. The value on the call is anything but this value.

Matches. Matches the given string or regular expression.
caller_state:=~california|new york

Doesn’t match. The value tagged on the call doesn’t match the given string or regular expression.

Numeric, Date, and Date-time

We now support a full range of operators on numeric, date, and date-time Tags.

You can create ranges by adding more than one Tag. A Buyer tagged with loan_amount:>100000 andloan_amount:<600000 will only receive calls where the caller is looking for a loan between $100,000.00 and $600,000.00.

== [default]
Equals. The value on the call is exactly this value.

Not equal to. The value on the call is anything but this value.

Less than. The value on the call is less than the given value.

Greater than. The value on the call is greater than the given value.

Less than or equal to. The value on the call is not greater than the given value.

Greater than or equal to. The value tagged on the call is not less than the given value.

sub_id:test and sub_id:==test in our system is the same thing. It’s a programming operator and not the same as query strings.

System Tags

All tags in the Retreaver system have been mapped to tag types. Calls are dynamically tagged with the value that would usually be used as a replacement token, as necessary.


No calls before a certain date

Tag your Buyer with call_start_time:>2014-07-17 to ensure they don’t get calls before July 17 2014.

Block calls from a certain Publisher

Tag a Buyer with publisher_id:!=1000 to block calls from Publisher 1000 from being routed to it.

No conversions after a certain date

Create a conversion group and tag it with call_end_time:<2014-09-01 to ensure a conversion isn’t triggered after August 31, 2014. Change the default conversion group to have a very high seconds value so it never converts.

Available Tags

Text Tags

The ID of the Retreaver campaign the call went through.
The Publisher ID of the party responsible for the call.
The first name of the party responsible for the call.
The last name of the party responsible for the call.
The company name of the party responsible for the call.
The ID of the Buyer the call was routed to.
The sub-id ID responsible for the call. (Example: Bing)
The phone number the caller used to call in.
The Retreaver UUID for the call.
The secret key used to postback conversion information about the call.
The phone number of the caller as it appeared on Caller ID.
The caller’s city based on their phone number, or their precise city if they entered a zip code.
The caller’s state based on their phone number, or their precise state if they entered a zip code.
The zip code the caller entered, if any.
The country of the caller, based on their phone number or zip code.
The number of the Buyer the call was routed to.
The URL of the MP3 recording for the call.
The status of the call when it ended.
Who hung up the phone first: caller or buyer.
Whether the call converted.true or false. Note: This will be a boolean tag in an upcoming release.
Whether the call was a duplicate of a previous call.true or false. Note: This will be a boolean tag in an upcoming release.
The name of the conversion criteria that was used for the call.

Date-time Tags

When the caller called the trackable phone number.
When the caller was forwarded to a Buyer.
When the call ended.

Numeric Tags

The Retreaver system Buyer ID of the party the call was routed to.
The number of seconds the caller was on the line with the Buyer.
The total duration of the call, from start to finish, in seconds.
The total number of minutes you were billed for the call.
The price per minute you were billed for the inbound call.
The price per minute you were billed for the outbound call.
The total cost you were charged for this call.
The conversion timer that was reached.
The amount earned on the call, according to the conversion settings.
The cost of the call, not including Retreaver charges, according to the conversion settings.

Redirecting Calls to Another Campaign

| Angela Dougherty

Sometimes Campaigns receive calls for which there is no Buyer available, either because the call has incompatible Tags, or because all the Buyers on the Campaign are closed or capped or otherwise unavailable to receive calls. Retreaver makes it easy to route calls to a different Campaign in situations like this.

However, you may be able to just add an overflow Buyer. If so, you can set that Buyer to a priority of 99 in order to be considered last. Check out our support page on Priority and Weight for more information.

Diverting Calls with No Matching Buyers


Adding a “no buyers match” Routing Setting to a Campaign.

Perhaps all your Buyers are tagged with mortgage:refinance, and you have a separate Campaign that you use only for purchase leads that uses Buyers tagged mortgage:purchase. In this case, edit the Campaign, adding a “When no buyers match” routing setting. Select “redirect to campaign” as the action and add your purchase campaign to the field.

Using this feature you can route calls to multiple campaigns depending on the Tags present on the call. If you also have a campaign with Buyersthat are tagged mortgage:va, you can also add it in the field and only calls thus tagged will be routed to it.

Re-routing calls based on any other action

You can use the “redirect to campaign” routing action for any of the other available routing scenarios. Calls will only be routed to a campaign that has open Buyers that match the call’s tags, so feel free to include multiple campaigns if necessary.

Ensuring Every Call is Answered

January 28, 2016 | Angela Dougherty

Whether dealing with customer support or inbound sales, it’s important to make sure every call is answered without subjecting callers to lengthy hold times, avoiding abandoned calls.

But what good is having the most flexible call routing technology in the industry if you’re routing to someone that never answers the phone?


Setting a ‘Timeout’ value by creating or editing a Buyer.

Retreaver allows you to detect ringing after you dial your destination. The “Timeout” feature allows you to set a maximum number of seconds to wait for the call to be answered before moving on to the next destination. If you have many different destination numbers that can take a call, we suggest setting this value very low, so you don’t waste much time waiting for any one destination to answer.

In cases where each caller is only routed to one destination (like if you’re selling “exclusive leads”), it’s advisable that you set the timeout value to be 60 seconds or higher since each call is only routed to one destination, giving your buyer plenty of time to answer the call.

Press 1 to Accept

To further ensure calls are answered by a human, you can add a “Press 1 To Accept” prompt to your campaign. This is a prompt that only the dialed party hears when they answer the call, and they will have to the 1 button on their keypad before the caller is connected. Like a whisper prompt, you can use it to pass information about the caller to the call recipient using text-to-speech and dynamic tag replacement.


Another powerful way Retreaver allows you to quickly route and connect calls is through our simuldialing feature. When creating a Buyer group, you can configure the destinations in the group to be simuldialed. This will dial all the numbers at once, awarding the call to the first person to pick up.

You can use this feature in tandem with our “Press 1 to Accept” and “Press 1 Too Slow” prompts on the Campaign in order to award the call to the first agent that presses 1.

Note: In-band signal monitoring is not currently available for destinations that have been simuldialed.

Extensions by Retreaver

September 21, 2015 | Jason Kay

Creating a new Number Pool using Extensions
Creating a new Number Pool using Extensions.

Ever since the invention of the telephone in 1878, businesses have been communicating with the power of voice. Since 1882, companies have been using internal private switches, now commonly known as a PBX to route calls.

In the old days, in order to route calls, switchboard operators would connect wires from the source (caller) to the destination (the call recipient).

Much like switchboard operators connected callers with their respective parties, today Retreaver announces Extensions. Extensions, is a much requested feature: connecting visitors to a website with someone who knows exactly who they are and why they’re calling through 1 phone number: by bridging the PBX technology of old with the internet.

Now Retreaver can follow all your customers on their journey interacting with your company, and tell you everything they have done, and everything they need, with only one phone number for your entire organization. Extensions can be used to provide cost effective, accurate attribution, provide personalized customer experiences or promotional codes. Assign extensions to individual support agents, sales reps or to VIP customers. The applications are only limited by your imagination. Contact Retreaver today and start using Extensions in your business.

Configuring your Extension Pool

Creating and using an Extension Number Pool

| Jason Kay

Creating a new Number Pool using Extensions.
Creating a new number pool using extensions.

Extensions allow you to create virtual phone numbers that work just like other phone numbers in Retreaver. Extensions are useful because they allow you to track many different visitors without paying the monthly costs associated with having thousands of phone numbers.

The easiest way to start using extensions is to create a number pool that creates extensions automatically based on the various attributes passed in via your landing page.

You can make entering the extension more user friendly from a marketing perspective by re-framing the number as an “offer number” for say a travel vertical, or a “computer number” in the tech support vertical.

Creating a number pool using extensions

To create a number pool that uses extensions, browse to the create new number pool page, and click the “Extensions” option as seen above.

We suggest setting an extension length of 4, since this allows for up to 9000 extensions, and keeps the length of the extension the user has to enter reasonable. Note that if you do plan on having that many extensions, or more, you’ll need to contact your account executive as currently extension pools are limited to 2000 like normal number pools.

You can always increase the extension length, but it cannot be decreased, so start small.

Setting the base number

Setting the base number.
Setting the base number on an extension number pool.

Each extension pool requires a base number set, which all extensions are based on. You can create a new base number associated with a campaign, or choose an existing one.

Displaying numbers with extensions on your website

Using our Retreaver.js JavaScript library you can easily display extensions on your website, and even make the links clickable for users on mobile devices.

In the above example, we request a number from Retreaver, and then pop the number with the extension into a mobile-ready link.

There’s no need to use the standard +18005550123 x 3444 format, you can phrase it any way you want. You’ll probably see higher conversion rates if you call it an exclusive offer ID or something else that’s relevant to your business.

We’ve linked the number in format tel:+18005550123,,5000 where 5000 is the extension. This causes iOS devices to automatically enter the extension, routing your caller automatically like with any normal phone number!

Bypassing Extensions

This can only be done on mobile, you can hyperlink the number as:  <a href=“[plain_number],,[extension]”>Call [number] using Promo ID: [extension]</a>

Retreaver Results

June 14, 2014 | Jason Kay

For most lead generators, inbound sales calls are distributed to buyers on a 1-to-1 basis. Each caller is routed to a single buyer. But what if you could allow consumers to call all your buyers?

Introducing Retreaver Results

Retreaver Results is a new API that facilitates the display of individual trackable phone numbers for each Buyer on a campaign. The new Results functionality allows consumers to comparison shop, delivering fully qualified leads to multiple buyers.

Click Here to View our Demo Site

Retreaver Results follows all your existing business logic on Buyers, like business hours, caps, and tag filters. Ask your visitors for their zip code, and pass that information along to the results.js script to filter Buyers by geo. Any tags that can be used in the Retreaver system can be passed to Retreaver Results to determine the Buyers you want displayed.

Once the visitor dials in, they’ll be routed directly to the Buyers they chose, without any unnecessary IVR prompts.

Getting started

The results.js code. The show_key is specific to your campaign, retrieve it form your campaign page.

Simply add the results.js code to your thank you page, and append any tags you want to pass in via the query string. Above, we pass in the consumer’s zip code as 90210 so we only show Buyers that can take calls from their area.

For each Buyer you want to display, create a <div> element with ID matching cp-target-3410 where 3410 is the Retreaver system Buyer ID. You should wrap all the Buyer divs in a single parent div element. We’ll dynamically hide and re-arrange the cp-target divs depending on which Buyers can receive a call from the consumer, and with respect to your priority and weight settings.

If you’re using Buyer groups and you only want to show one entry per group, you can add a <div> element with ID matching cp-target-group-501 where 501 is the Buyer group ID. When a visitor calls the displayed number, they’ll be routed as normal to one of your grouped Buyers. This is useful when you have multiple Buyers for the same company, each with different hours of operation.

Like with our number display script, use replacement tokens [number] and [plain_number] within each cp-target div to insert the formatted phone number and unformatted phone digits of the trackable number.

We’ll only display the buyers that match your visitor, and that are open and able to receive a phone call.

You can put any content you want in the Buyer/target divs, like a logo, the name of the buyer, and a description. We’ll only display the Buyers that match and are open and able to receive a phone call. Set the divs as hidden by default to make sure they don’t “flash” while the display script is executing.

If you’re passing in arbitrary tags like zip-code tags, you’ll need to have a number pool configured for the campaign so that we can dynamically assign phone numbers for the visitor to call.

No matching Buyers

When there’s no Buyer that can serve the visitor, we enable the display of div with ID cp-targets-none. This div will be hidden if there are Buyers displayed.

jQuery integration

When we’re done processing the results and Buyers have been displayed, we fire event cp-results-processed on $(document).

Demo App
Our demonstration implementation, a lead-gen form for auto insurance.

View our demo app at This app features the option of choosing between click-to-call or Retreaver Results.

The code for this site is open source. Take it and use it in your own project.

Consumers enter their zip code and the results are automatically limited to the given geo. All calls are automatically tagged with whether or not the visitor already has insurance, and this information is passed to the Buyer via a whisper prompt.

The code for this site is freely available as a Ruby on Rails app, which can be easily adapted to suit your needs. Please fork the project and send us a pull request with your improvements. We’re looking forward to seeing your Results!