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://api.routingapi.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://api.routingapi.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.