Real-Time-Bidding API

Real-Time-Bidding API

The Retreaver Real-Time-Bidding API allows users to create an agent pre-qualifying ping/post system, which seeks to return an available endpoint/buyer picked out from their existing Retreaver campaign routing pool.

The RTB API effectively allows lead generators the ability to ping Retreaver campaigns for a transfer number, by prequalifying the lead and reserving an available buyer to take their call.

Real-Time-Bidding Workflow Overview

Lead generators will send a POST request to the RTB API, and the following events will occur:

1. Retreaver will tag the caller id with a publisher id & any data/tags provided in the RTB request.
2. Retreaver will trigger any 'Passthrough' webhooks present on the campaign, checking for agent availability & evaluating ping post responses to determine dynamic payouts.
3. If a buyer/agent is available & the lead fulfills any present Geo/Zip/Lead filters - the RTB request will return an inbound_number, conversion timer and payout value.
4. The publisher will route the call using the inbound_number returned by the request.
5. If the connected call duration exceeds the conversion buffer, Retreaver will convert the call based on the provided conversion criteria placed on the campaign.

Creating A Retreaver 'Real-Time-Bidding' Link

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:

Configuring the RTB Postback Key settings:

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]

RTB Posting Instructions for Publishers

Retreaver requires that each RTB request includes a 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 meet 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.

Working With Downstream Bidding Webhooks

Triggering Downstream Bidding Webhooks when using RTB

When working with Downstream Bidding Webhooks, (such as having Buyers using Retreaver or other call tracking platforms), its important to set the webhook trigger from "Start - When a call starts" to "Passthrough" - This ensures the webhook will trigger when an RTB request is received from a publisher.

Creating Conversion Criterias for buyers using Bidding Webhooks

Downstream bidding webhooks typically return a dynamic/unique conversion timer and bid value. By default, the webhook configurator "Auto-Buyer" setup option will create a conversion criteria on the buyer profile, but this will not apply towards a publisher payout. If your publisher reports that they are receiving bids of $0, its because a conversion criteria containing a payout revshare value must be created on the campaign.

On the Retreaver campaign containing the RTB key, you will need to create a conversion criteria utilizing the timer & bid tags specific to a webhook-integrated buyer.

1. For the example below, we have a buyer using the tags retreaver_rtb_44407_timer & retreaver_rtb_44407_bid.

2. We then set the Payout as a 70% percentage of the bid value.

3. We also tag the buyer to the conversion criteria, so it is chosen anytime this particular buyer is chosen by the Real-Time-Bidding reservation system.

This ensures that if this buyer is chosen via RTB, the publisher will receive 70% of the retreaver_rtb_44407_bid value, and will receive a conversion required duration of retreaver_rtb_44407_timer.

Real-Time Bidding, Confirmations and Caps

When Retreaver receives a Real-Time Bidding (RTB) request, it can reserve a call in the Call Buyer caps even before the call actually arrives, since the system expects the call to follow. The caps are Concurrency Cap, Hard Cap, Hourly Cap, Daily Cap, Monthly Cap.

In practice, thousands or even tens of thousands of RTB requests may be received for every single call, so reserving in advance is usually unnecessary.

If you want calls to be reserved in the Caps at the RTB stage, you must now explicitly enable this behavior by setting add_to_caps_on_status_reserved for the Postback key (Visit Campaign → Scroll to Postback Keys), or require the Publisher to confirm the reservation by sending a second status="confirmed" request.

Confirming a reservation

Retreaver allows publishers to check for availability, and if they decide to send the call, they can ensure an agent is reserved by sending a second request with status="confirmed". When this confirmation request is received, Retreaver checks the configured caps for the Call Buyer/Endpoint. If sufficient capacity is available, the Call Buyer/Endpoint is reserved.

Check out the full documentation at Retreaver API Docs

How To Troubleshoot RTB Requests

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.

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 queue, 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.

Frequently Asked Questions

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.

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 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, their system may have decided to route to another buyer if a higher bid was offered by a competing affiliate.

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 Retreaver campaign may have decided to route to another buyer if a higher bid was offered by a competing affiliate.

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 is used to detect & prevent spam, or temporarily bottleneck a sudden surge of traffic, or filter out recently sent/received or duplicate leads from being evaluated.

Other platforms may implement similar systems to 'rate limit' or 'deflect' RTB requests. These systems are also attempting to detect & prevent spam, or temporarily bottleneck a sudden surge of traffic, or filter out recently sent/received or duplicate leads from being evaluated.

RTB Status Terminology