Working with the Retreaver 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.



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:




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:

Note regarding conversion criterias: 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.

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. 


Step 4) 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:


Provide the RTB link over to your call lead generator, and instruct them to send a POST request to the provided webhook at the beginning of their engagement.

If the campaign contains an available agent at the time of the request, Retreaver will return a transfer number under a JSON response for them 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"

If your publishing partner generating calls is not a Retreaver user, they 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:


Step 5) Real-Time-Bidding Workflow Summary

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 an publisher id and any other provided tags.
  2. The publisher will route the call using the inbound_number returned by the request.
  3. Retreaver will convert the call based on the provided conversion criteria placed on the campaign.


Your publishing partner will now be able to request for a reserved transfer number from your campaign and route calls to a prequalified available buyer. They will also receive credit for any converted calls that they successfully transfer over to a Retreaver campaign.

0 out of 0 found this helpful



Please sign in to leave a comment.