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
| Property | Description |
| 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
| Parameter | Description |
| 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
| Property | Description |
| 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
| Parameter | Description |
| 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
| Property | Description |
| 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
| Parameter | Description |
| 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
| Parameter | Description |
| 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
}
}
- Resources
- User Manual
- Forums
- Help Videos
- Blog
- FAQ's
- Office Phone System Settup
- PBX Setup
- SIP Phone System
