Configuring the Retreaver Call Reservation API to ping Campaigns for Buyers


Call Reservation API

The call reservation API allows users to create a ping webhook that asks Retreaver to return an available endpoint from your campaign. This feature allows publishing partners to ping your campaigns and ensure that there is a valid transfer number available to take their call.

Sending a POST request to this webhook will assign an affiliate identifier to the provided caller id and return back a transfer number that your partners can then use to route calls into your campaign. 


Step 1)

Contact Retreaver support to enable the Call Reservation API for your listed company ID.


Step 2)

Head to the desired campaign that will be purchasing calls and create a new postback key at the bottom of the campaign overview page:



Step 3)

Configure the webhook to include any tags that you require the seller to provide, at the very least we will require an affiliate_id + caller_number parameter. They may also provide additional caller details by appending them to the end of the webhook:[caller_number]&affiliate_id=[publisher_id]&caller_zip=[caller_zip]&current_carrier=[current_carrier]&first_name=[first_name]&last_name=[last_name]


Step 4)

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



Step 5)

Provide the created webhook link over to the selling party, and instruct them to send a POST request to the provided webhook. If this specified Retreaver campaign contains a valid & available buyer at the time of the request, Retreaver will return a transfer number under a JSON response. They will then need to parse the "inbound_number" property to extract the desired transfer number.

Example JSON response parsing using JavaScript:

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": []


Step 6)

They can then route the call to the provided inbound_number where the following actions take place:

  1. Retreaver will receive the call.
  2. Tag the call with an affiliate id and any other provided tags.
  3. Route the call to the inbound_number buyer on the campaign.
  4. Convert the call based on the provided conversion criteria placed on the campaign. Ideally they will have a conversion criteria created specifically for that affiliate_id on the campaign.


Optional Step 7)

If the selling party pinging your campaign is a Retreaver user, they will need to also create a new buyer using the [inbound_number] tag as the transfer number that will be dynamically substitued using the ping webhook.

They must then create a start ping webhook on their campaign that will fire the call reservation webhook into your campaign at the start of a call:

1) Creating the dynamic buyer using the inbound_number tag that the webhook response will fill. They will place this newly created buyer on the campaign that they intend to sell calls into.

2) Creating the start ping webhook that will ping the purchasing campaign for a buyer at the start of a call.


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.