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 an available endpoint pinged from their Retreaver campaigns for 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:

https://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456&affiliate_id=[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.

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 number on the company associated with the call reservation 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) 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:
https://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456&affiliate_id=4321ABCD&caller_number=[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": {
        "uuid": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
        "inbound_number": 11234567890,
        "caller_number": "+10987654321",
        "status": "no-target",
        "expires_at": null,
        "claimed_at": null,
        "wiped_at": null,
        "call": {
            "uuid": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
            "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:
JSON.parse(Webhook_Response).call_reservation.inbound_number;

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.
   
   

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.