Working with the Retreaver Real-Time-Bidding API

Step 1) Enabling Real-Time-Bidding for your Retreaver Account

Contact Retreaver support to enable the Real-Time-Bidding API for your listed company ID. Retreaver support will enable and configure your account to support RTB using your company ID. 

Step 2) Creating a Real-Time-Bidding Webhook

As the campaign owner looking to purchase calls from a lead generator, navigate to a Retreaver campaign overview page and create a new postback key for Real Time Bidding:

How to Add a new RTB Postback Key:

Note: You do not need to create more than one RTB postback key on a campaign. If one is already present, use that one instead and swap out the publisher ID as covered in the next step.

Configuring the RTB Postback Key settings:

Note: The TTL (Time-To-Live) value dictates how long to keep a successful RTB reservation open pending a transfer from the publisher, the default recommendation is 15 seconds.

Note: The Timeout period dictates how long to wait for downstream 'PassThrough' webhooks to complete before continuing, the default recommendation is 5 seconds.

Completed RTB Postback Key:

Step 3) Configuring the Real-Time-Bidding Webhook

Include a publisher_id into the webhook under the right hand side of the "publisher_id=" parameter so that Retreaver can identify who sent the RTB request.

Append the publisher id to the RTB webhook to complete the RTB link:

https://rtb.retreaver.com/rtbs.json?key=1915260e-da0c-4443-a35b-8fb9d9843e42
&publisher_id=4321ABCD
&caller_number=[caller_number]

Note regarding conversion criteria's: You will also need to create a new conversion criteria on your campaign matching this publisher if it has not already been created in order to accredit this publisher for any converted calls that they have routed to your campaign.

Failure to create a valid conversion criteria for this publisher will force the RTB request to return a payout of '$0', which will impact the likelihood the publisher will be willing to route the call over to your campaign. 

Optional: Specify which routing number to use: If you would like to control which Retreaver tracking number is used to route and receive the call, you can append an additional "&inbound_number=+18885551234" parameter. The value of the inbound_number parameter can be any Retreaver tracking number on the campaign with the RTB postback key. Note, this will not tag the call with any tags present on the tracking number - this feature was added to support overridden routing paths using unlocked tracking numbers. 

Posting Instructions for Publishers

Retreaver requires that each RTB request includes an publisher_id and caller_number parameter value. They may also provide additional caller details by appending them to the end of the webhook similar to example below:

https://rtb.retreaver.com/rtbs.json?key=1915260e-da0c-4443-a35b-8fb9d9843e42
&publisher_id=[publisher_id]
&caller_number=[caller_number]
&caller_zip=[caller_zip]&caller_state=[caller_state]&first_name=[first_name]&last_name=[last_name]

Be sure to send a POST request to the provided RTB webhook.

If the campaign contains an available agent at the time of the request, Retreaver will return a transfer inbound_number under a JSON response for you to route into.

Example Response Payload:

{
"uuid": "66b905ef-bc03-420e-ad43-e8eeae03918f",
"status": "reserved",
"retreaver_payout": 1.173,
"retreaver_seconds": 95,
"inbound_number": "+18444021146",
"expires_at": "2024-05-29T16:16:18.246Z"
}

You will then need to manually parse the "retreaver_payout", "retreaver_seconds", "inbound_number" properties to extract the desired transfer number.

Example JSON response parsing using JavaScript:
JSON.parse(Webhook_Response).retreaver_payout;
JSON.parse(Webhook_Response).retreaver_seconds;
JSON.parse(Webhook_Response).inbound_number;

Provided that the Conversion payout and conversion buffer seconds meets your criteria, please transfer the provided caller ID to the inbound_number returned by the RTB request.

You will now be able to request for a reserved transfer number from your affiliates campaign and route calls to a prequalified available buyer. You will receive credit for any converted calls that you successfully transfer over to a Retreaver campaign.

If the campaign contains an available agent at the time of the request, Retreaver will return a transfer inbound_number under a JSON response for you to route into.

If no agent was available at the time of the RTB request, there will not be an inbound_number in the response body of the RTB request.

In order to determine the exact reason why no buyer was available, the RTB UUID will need to be forwarded to the Retreaver campaign owner for them to look into the RTB request further.

Note that the RTB UUID will expire within 24 hours, as the RTB request database is regularly flushed. 

Example Response:

{
"uuid": "1212e30a-cff2-4f2f-ae84-dfdf5b952204",
"status": "rejected",
"info": "Unable to determine payout until the call converts"
}

The Retreaver account owner would copy the UUID and navigate to the following url: https://retreaver.com/call_reservations/1212e30a-cff2-4f2f-ae84-dfdf5b952204

Navigating to the above URL will bring them to the following page:

From this page, click on the 'Call' link, where you can then view the call flow at the bottom of the page.

The call flow will then determine the exact course of events in the RTB request, pay particular attention to the attempted buyers on the routing que, as it will report if any buyers were closed, were filtered out, or were unavailable and for what exact reason.

This information is limited to the Retreaver account holder as it may contain sensitive information that should only be visible to the campaign owner.

What does "The call reservation expired because the TTL was reached" mean?

Successful RTB requests will reserve a routing number and buyer, however these call reservations have a time out period which is 30 seconds by default. If the publisher does not route the submitted caller ID within the timeout period, the call reservation expires.

Why are my publishers not routing calls to my campaign?

Not every successful RTB call reservation will result in a call, as your publishers are likely communicating with multiple other systems and buyers, which are all competing for the same call. Simply put, they could have decided to route to another buyer due to a higher bid being offered.

Why are my buyers reporting we are not routing calls to them?

Not every successful bid response will result in a call, as your campaign is likely communicating with multiple other systems and buyers, which are all competing for the same call. Simply put, the campaign decided to route to another buyer due to a higher bid being offered.

What does a "status":"no-target" RTB response mean?

A status of 'no-target' means that no buyer was available to take the call. We recommend that you send the RTB UUID to your buyer and ask them to review the call flow to determine why no bid was returned. It could be that certain required caller lead details were missing, or that a downstream buyer down the chain has strict geo/zip filtering. Reach out to your buyer for more information.

Why are my publishers reporting that RTB is not returning bids?

The RTB campaign had no compatible buyer available, it could be that none of your buyer filters matched or that your dynamic buyers did not offer a bid for that lead.

Why are my dynamic buyers not returning bids?

In order to determine why your dynamic buyers are not returning bids, it is best to look at the 'fired pixels' page when viewing a call flow, this will help you analyze which API requests were made, and what the API response was. It could be that the buyer system was closed, the supplied lead request was missing some critical details, or the API could not find a match for that caller at that time.

Can publishers send a fake caller id to determine buyer availability?

The caller ID supplied to a RTB request must match the transferred lead caller id in order to successfully route to the reserved buyer. This is because the RTB system has reserved a buyer specific to the supplied caller ID in the request.

What is the 'inbound number' parameter used for?

The inbound number is an optional parameter used to force a Retreaver tracking number as an inbound_number response. This allows for a consistent routing number when making RTB requests.

Can a publisher supply lead information on the RTB request?

Publisher can supply caller lead information by appending additional &key=value parameters when making RTB requests.

What is the Retreaver Ping Shield, and what does it do?

The Retreaver Ping Shield prevents publishers from submitting rapid identical RTB requests towards your Retreaver campaigns, preventing duplicate call reservations from being processed.