Working with the Retreaver Call Reservation API

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]

Note regarding conversion criterias: 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.

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 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) Posting Instructions for Publishers

Retreaver requires that each call reservation 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://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 an 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.