Call Reservation API [deprecated]

Call Reservation API

The Retreaver call reservation 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 Call reservation 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 Call Reservation for your Retreaver Account

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

Step 2) Creating a Call Reservation 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 Call Reservation 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 call reservation request.

Append the publisher id to the call reservation webhook to complete the call reservation link:

https://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456
&publisher_id=4321ABCD
&caller_number=[caller_number]

Step 4) Posting Instructions for Publishers

Retreaver requires that each call reservation request includes a 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://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456
&publisher_id=[publisher_id]
&caller_number=[caller_number]
&caller_zip=[caller_zip]&caller_state=[caller_state]&first_name=[first_name]&last_name=[last_name]

Provide the call reservation 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

{
    "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 5) Call Reservation Workflow Summary

Lead generators will send a POST request to the call reservation API, and the following events will occur:

1. Retreaver will tag the caller id with a 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.