RingRoost API Documentation

The RingRoost API allows you to manage your account features such as accessing call detail records, purchasing and managing phone numbers, getting account details and more.

Getting Started

The RingRoost API is built using HTTP REST protocol, it currently only supports JSON for transport. Start out by trying out the this example of getting a list of your call detail records. (Tip: You can use your browser to interact with the API.)

AUTHORIZATION

RingRoost uses basic HTTP authorization, with the "API User" & "API Password" that can be found on your account overview https://www.ringroost.com/account.php. Basic authentication simple requires you to send your API username and password on every request in the HTTP Authorization header as shown below. Username and password should be base64_encoded as shown in the below format.

Request Examples

  • CURL
  • PHP
 curl -G  'https://www.ringroost.com/api/cdrs' -u '{api_user}:{api_pass}' 
 
 <?php

                $url="https://www.ringroost.com/api/cdrs";
                $api_user="nmc4H9rwjXDtHQbXIaaw5ehT0I";
                $api_pass="Zhj72aFuKe9n005GoKF9ApnJHi";

                $ch = curl_init($url);
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                curl_setopt($ch, CURLOPT_HTTPHEADER,array("Authorization: Basic " . base64_encode("$api_user:$api_pass")));
                $result = curl_exec($ch);
                curl_close($ch);
                echo $result;
?>
         

Response Examples

  • 200
 
{
    "start_date": "2015-04-01 00:00:00",
    "end_date": "2015-04-01 00:00:00",
    "cdrs": [
        {
            "id": "225719",
            "pbx_id": "211",
            "call_date": "2015-04-03 14:46:04",
            "inbound_from": "19196514034",
            "inbound_to": "",
            "inbound_duration": "22",
            "inbound_cost": 0,
            "outbound_to": "17049417531",
            "outbound_duration": 22,
            "outbound_cost": 0.02,
            "status": "ANSWER",
            "total_cost": 0.02
        },
        {
            "id": "225718",
            "pbx_id": "211",
            "call_date": "2015-04-03 14:44:51",
            "inbound_from": "19196514034",
            "inbound_to": "",
            "inbound_duration": "35",
            "inbound_cost": 0,
            "outbound_to": "17049417531",
            "outbound_duration": 35,
            "outbound_cost": 0.02,
            "status": "ANSWER",
            "total_cost": 0.02
        }
    ]
}
        

Call Detail Records (CDR's)

The Call Details Records allows you to query all of your call logs, you can filter by date range and by pbx_id. Filtering by pbx_id allows resellers to bill clients based on the PBX the call is going to/from. By default all CDRS through the first of the current month will be returned.

Resource Object

PropertyDescription
id Unique identifier for this call detail record.
pbx_id Unique identifier for the PBX that this call was sent to or originated from.
call_date Datetime value of when the call was initiated.
inbound_from The caller ID that originated this call.
inbound_to The RingRoost phone number that the call was sent to.
inbound_duration Duration of the inbound leg of this call.
inbound_cost Total cost of inbound leg.
outbound_to The phone number of the outbound call leg.
outbound_duration Duration of outbound call of this leg.
outbound_cost Total cost of outbound leg.
status The last status of the call: NO ANSWER| CONGESTION | FAILED | BUSY | ANSWERED
total_cost The total cost of the inbound and outbound leg of the call.

/GET

 https://www.ringroost.com/api/cdrs 

Gets call detail records.

/GET PARAMETERS

ParameterDescription
state_date(optional) Date in mm/dd/yyyy - API will return all CDRS after this date.
end_date(optional) Date in mm/dd/yyyy - API will return all CDRS before this date.
pbx_id(optional) Only return CDRS associated with a particular PBX. PBX ID can be found by looking at the url when on your PBX.

Request Examples

  • CURL
  • PHP
  curl -G  'https://www.ringroost.com/api/cdrs?start_date=03/19/2015&end_date=03/20/2015&pbx_id=1534' -u '{api_user}:{api_pass}' 
 
<?php

        $url="https://www.ringroost.com/api/cdrs?start_date=03/19/2015&end_date=03/20/2020";

        $api_user="nmc4H9rwjXDtHQbXIaaw5ehT0I";
        $api_pass="Zhj72aFuKe9n005GoKF9ApnJHi";

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_HTTPHEADER,array("Authorization: Basic " . base64_encode("$api_user:$api_pass")));
        $result = curl_exec($ch);
        curl_close($ch);
        echo $result;
?>
         

Response Examples

  • 200
 
{
    "start_date": "2015-04-01 00:00:00",
    "end_date": "2015-04-01 00:00:00",
    "cdrs": [
        {
            "id": "225719",
            "pbx_id": "211",
            "call_date": "2015-04-03 14:46:04",
            "inbound_from": "19196514034",
            "inbound_to": "",
            "inbound_duration": "22",
            "inbound_cost": 0,
            "outbound_to": "17049417531",
            "outbound_duration": 22,
            "outbound_cost": 0.02,
            "status": "ANSWER",
            "total_cost": 0.02
        },
        {
            "id": "225718",
            "pbx_id": "211",
            "call_date": "2015-04-03 14:44:51",
            "inbound_from": "19196514034",
            "inbound_to": "",
            "inbound_duration": "35",
            "inbound_cost": 0,
            "outbound_to": "17049417531",
            "outbound_duration": 35,
            "outbound_cost": 0.02,
            "status": "ANSWER",
            "total_cost": 0.02
        }
    ]
}
        

Available Numbers

The Available Numbers resources allows for searching of phone numbers that can be purchased through the Phonenumber resource.

Resource Object

PropertyDescription
number Phone number with leading country code.
city City that the phone number is associated with.
state State that the phone number is associated with.
rate_center Rate Center that the phone number is associated with.
country_code Country Code that the phone number is associated with.
toll_free 1 for toll free numbers, 0 if not toll free.
sms_in 1 if SMS inbound capable, 0 if not.
sms_out 1 if SMS outobund capable, 0 if not.

/GET

 https://www.ringroost.com/api/available_numbers/{area_code} 

Searches for available phone numbers.

/GET PARAMETERS

ParameterDescription
area_code(required) Area Code to Search for Number
country_code(optional) Country code. Defaults to 1.

Request Examples

  • CURL
  • PHP
  curl -G  'https://www.ringroost.com/api/available_numbers/704 -u '{api_user}:{api_pass}' 
 
<?php

        $url="https://www.ringroost.com/api/available_numbers/704?country_code=1";

        $api_user="nmc4H9rwjXDtHQbXIaaw5ehT0I";
        $api_pass="Zhj72aFuKe9n005GoKF9ApnJHi";

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_HTTPHEADER,array("Authorization: Basic " . base64_encode("$api_user:$api_pass")));
        $result = curl_exec($ch);
        curl_close($ch);
        echo $result;
?>
         

Response Examples

  • 200
 
{
    "count": 3,
    "area_code": "704",
    "country_code": 1,
    "available_numbers": [
         {
            "number": "17043258102",
            "city": "NEWTON",
            "state": "NC",
            "rate_center": "NEWTON    ",
            "country_code": "1",
            "toll_free": 0,
            "sms_in": 1,
            "sms_out": 0,
            "voice": 1 
        },
        {
            "number": "17043258110",
            "city": "NEWTON",
            "state": "NC",
            "rate_center": "NEWTON    ",
            "country_code": "1",
            "toll_free": 0,
            "sms_in": 1,
            "sms_out": 0,
            "voice": 1 
        },
        {
            "number": "17043258120",
            "city": "NEWTON",
            "state": "NC",
            "rate_center": "NEWTON    ",
            "country_code": "1",
            "toll_free": 0,
            "sms_in": 1,
            "sms_out": 0,
            "voice": 1 
        }
    ]
}
        

Phonenumber

The Phonenumber resource allows for purchasing available numbers and updating/provisioning your phonenumbers.

Resource Object

PropertyDescription
number Phone number with leading country code.
city City that the phone number is associated with.
state State that the phone number is associated with.
rate_center Rate Center that the phone number is associated with.
country_code Country Code that the phone number is associated with.
toll_free 1 for toll free numbers, 0 if not toll free.
sms_in 1 if SMS inbound capable, 0 if not.
sms_out 1 if SMS outobund capable, 0 if not.

/POST

 https://www.ringroost.com/api/phonenumber/{phonenumber} 

Purchases a phonenumber.

/POST PARAMETERS

ParameterDescription
phonenumber(required) Phonenumber with leading country code. ex: 17049417544. This may also be an area code with leading country code ex: 1704. If area code is given then 1 number will be purchased from that area code.

Request Examples

  • CURL
  • PHP
  curl -XPOST 'https://www.ringroost.com/api/phonenumber/17049417455 -u '{api_user}:{api_pass}'  
 
<?php

        $url="https://www.ringroost.com/api/phonenumber/7049417455";
        $api_user="nmc4H9rwjXDtHQbXIaaw5ehT0I";
        $api_pass="Zhj72aFuKe9n005GoKF9ApnJHi";

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_HTTPHEADER,array("Authorization: Basic " . base64_encode("$api_user:$api_pass")));
        $result = curl_exec($ch);
        curl_close($ch);
        echo $result;
?>

         

Response Examples

  • 201
  • 500
 
{
    "success": 1,
    "phonenumber_details":
         {
            "number": "7049417455",
            "city": "NEWTON",
            "state": "NC",
            "rate_center": "NEWTON    ",
            "country_code": "1",
            "toll_free": 0,
            "sms_in": 1,
            "sms_out": 0,
            "voice": 1 
        }
}
        
 
{
    "success": 0,
    "error"=>"Number is not available"
}

/GET

 https://www.ringroost.com/api/phonenumber/{phonenumber} 

Displays details about a phonenumber that you own.

/GET PARAMETERS

ParameterDescription
phonenumber(required) Phonenumber with leading country code. ex: 17049417544

Request Examples

  • CURL
  • PHP
  curl -G  'https://www.ringroost.com/api/phonenumber/7049416544 -u '{api_user}:{api_pass}' 
 
<?php

        $url="https://www.ringroost.com/api/phonenumber/7049416544?country_code=1";

        $api_user="nmc4H9rwjXDtHQbXIaaw5ehT0I";
        $api_pass="Zhj72aFuKe9n005GoKF9ApnJHi";

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_HTTPHEADER,array("Authorization: Basic " . base64_encode("$api_user:$api_password");
        $result = curl_exec($ch);
        curl_close($ch);
        echo $result;
?>
         

Response Examples

  • 200
 
{
    "phonenumber_details":
         {
            "number": "7049417455",
            "city": "NEWTON",
            "state": "NC",
            "rate_center": "NEWTON    ",
            "country_code": "1",
            "toll_free": 0,
            "sms_in": 1,
            "sms_out": 0,
            "voice": 1 
        }
}

RingRoost API

Authorization

CDR's

Available Numbers

Phonenumber

Stay connected with RingRoost