Configuring the Retreaver Call Reservation API to ping Campaigns for Buyers

Call Reservation API

The Retreaver call reservation API offers campaign managers the ability to create an inhouse ping/post system capable of returning dynamic endpoints from their Retreaver campaigns to prospective call generators. This feature subsequently offers publishing partners the ability to ping Retreaver campaigns for a transfer number available to take their call.


Step 1) Enabling Call Reservation

Contact Retreaver support to enable the Call Reservation API for your listed company ID. We will enable and configure your account to support call reservation using your company ID. 


Step 2) Creating a Call Reservation Webhook

If you are the campaign manager looking to purchase calls from a publisher, head to the desired campaign that will be purchasing calls. Navigate to the bottom of the campaign overview page and create a new postback key using the "+" symbol:



Step 3) Configuring the Call Reservation Webhook

Configure the webhook to include any tags that you require the seller to provide in order to make a valid connection with your endpoints such as lead ids, name, age or state.

Retreaver requires that each call comes with an affiliate_id and caller_number parameter at the very minimum. They may also provide additional caller details by appending them to the end of the webhook similar to example below:[publisher_id]&caller_number=[caller_number]&caller_zip=[caller_zip]&caller_state=[caller_state]&first_name=[first_name]&last_name=[last_name]

When a publishing partner sends a POST request using the above call reservation webhook, Retreaver will assign an affiliate identifier to the provided caller id and return back a potential transfer number to your publishing partner for routing.


Step 4) Assigning a publisher to a Call Reservation Webhook

Create a new publisher profile for the selling party if it does not already exist and copy/paste the publisher_id into the webhook under the right hand side of the "affiliate_id=" parameter so that Retreaver can identify who sent in the call reservation request:


Append the publisher id to the call reservation webhook like so:[caller_number]

Please ensure that your reporting and conversion logic matches this publisher profile moving forward. You will 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.


Step 5) Posting Instructions for Publishers

Provide the created webhook link over to your call publishing partner, and instruct them to send a POST request to the provided webhook at the beginning of their engagement. If the posted Retreaver campaign contains a valid & available buyer at the time of the request, Retreaver will return a transfer number under a JSON response for them to route into.

Example Response Payload:

    "call_reservation": {
        "inbound_number": 11234567890,
        "caller_number": "+10987654321",
        "status": "no-target",
        "expires_at": null,
        "claimed_at": null,
        "wiped_at": null,
        "call": {
            "formatted_caller_number": "(098) 765-4321",
            "status": "no-target",
            "start_time": null,
            "end_time": 1000000000000,
            "caller_number": "+10987654321",
            "target_id": null,
            "winning_leg_connected_at": null,
            "winning_leg_disconnected_at": null
        "matched_targets": [],
        "tag_values": [],
        "conversion_groups": []

If your publishing partner generating calls is not a Retreaver user, they will then need to manually parse the "inbound_number" property to extract the desired transfer number.

Example JSON response parsing using JavaScript:


Step 6) Call Reservation Workflow Summary

If your publishing partner was provided an available inbound_number to route into, the following actions will take place:

  1. Retreaver will tag the caller id with an affiliate id and any other provided tags.
  2. The publisher will attempt to route the call to the inbound_number buyer on the campaign.
  3. Retreaver will convert the call based on the provided conversion criteria placed on the campaign.

7) Additional Step for Retreaver Publishers

7A) If the publishing partner is a Retreaver user, instruct them to create a new buyer using the [inbound_number] tag as the transfer number, it will be dynamically substituted as a response to a post attempt.


The publisher will then need to place this newly created buyer on the campaign that they intend to sell calls from.

7B) They must also create a start ping webhook on the campaign intending to sell calls, this webhook will fire the call reservation webhook at the start of a call:

Creating the start ping webhook that will ping the purchasing campaign for a dynamic endpoint at the start of a call.

Note for Retreaver to Retreaver Call Reservations

Call reservation attempts between Retreaver users requires the buying party to use a campaign with no IVR's or prompts of any kind. The prompts layer will conflict with the call reservation attempt resulting in no "inbound_number" tag being returned to the publishing party.

If you are a call buyer and wish to utilize the call reservation feature from within a campaign that includes prompts, please use the below webhook URL to bypass the prompts system on your campaign that you can then forward to your publishing / call generating network. 

The publisher in this case would use the following method, note that the reservation_key and affiliate_id must be filled out by the call buying party, the rest of the fields will be auto populated by the publishing / call generating party:[reservation_key]&affiliate_id=[affiliate_id]&number=[nanp_caller_number]&uuid=[call_uuid]&key=[call_key]



Your publishing partner will now be able to request a transfer number from your campaign and directly route calls to an available buyer as well as receive attribution for any converted calls that they transfer over to you.

0 out of 0 found this helpful



Please sign in to leave a comment.