API version 3

It is very easy to manage numbers and check the balance without going through the Console with our easy-to-use and intelligent API. There are no messy libraries or tons of code to manage. The API is available with Premium account only.

Endpoint

https://www.groovl.com/api/v3.php

The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Authentication

You will need to post user and token with each request for authentication. To obtain meant credentials, please refer to your account settings.

Structure

Please post your requests as JSON. API returns all data as JSON. Do not forget to transmit a resource:

search

Search for available phone numbers.

PropertyDescriptionRequestResponse
pidthe ID of this phone number +
phonean available telephone number
The '*' character will match any digits.
++
carrierthe name of network +
countrythe ISO country code of this phone number++
resourceused resource++
resolution'ok' or 'failed' with some error message  +
PHP EXAMPLE REQUEST

$postfields = array(
	"user" => "xxxxx",
	"token" => "yyyyy",
	"resource" => "search",
	"country" => "GB"
);

$data = json_encode($postfields);

if (!$ch = curl_init()) {
	exit;
}

$headers = array(
	'Accept: application/json',
	'Content-Type: application/json',
);

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_URL, "https://www.groovl.com/api/v3.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$output = curl_exec($ch);
curl_close ($ch);

print_r($output);
EXAMPLE RESPONSE

{
	"resource": "search",
	"resolution": "ok",
	"response": [
		{
			"pid": "aMdVva9gHkAVBb13qrpR",
			"phone": "(+44) 75XX-XX5-815",
			"carrier": "EE / T-Mobile",
			"country": "GB"
		}, 

	...

		{
			"pid": "lJP8PjTrTmsJavjlR80s",
			"phone": "(+44) 73XX-XX0-993",
			"carrier": "EE / T-Mobile",
			"country": "GB"
		}
	]
}

plans

Search for available operating plans.

PropertyDescriptionRequestResponse
countrythe ISO country code of this phone number++
planthe ID of this operating plan +
titlethe plan title +
daysbilling cycle in days +
setupthe setup fee +
renewthe renewal fee +
premiumthe plan is available with a premium account +
resourceused resource++
resolution'ok' or 'failed' with some error message  +

activate

Allocate phone number. Before trying to activate a number, use 'search' to retrieve the list of available numbers.

PropertyDescriptionRequestResponse
pidthe ID of this phone number++
planthe ID of operating plan++
phonetelephone number +
resourceused resource++
resolution'ok' or 'failed' with some error message  +

list

Search for active (live) phone numbers associated with your account.

PropertyDescriptionRequestResponse
phonetelephone number
The '*' character will match any digits.
++
statusthe status of number
'1' = Allocation, '2' = Live, '3' = Released, '4' = Storage;
++
countrythe ISO country code of this phone number++
expiresdate of auto renew or expiration (MST) +
autorenewauto-renew:
'0' = On, '1' = Off;
++
planthe ID of operating plan +
pagesa total number of pages
10 numbers per page
 +
pagecurrent page++
resourceused resource++
resolution'ok' or 'failed' with some error message  +

settings

Number settings.

PropertyDescriptionRequestResponse
phonetelephone number++
countrycountry +
namefriendly name +
expiresdate of auto renew or expiration (MST) +
planthe ID of operating plan +
feethe renewal fee +
autorenewauto-renew:
'0' = On, '1' = Off;
 +
toforward all inbound messages to:
'0' = Disable, '1' = E-mail, '2' = URL;
 +
addressforwarding address +
resourceused resource++
resolution'ok' or 'failed' with some error message  +

update

Update phone number properties.

PropertyDescriptionRequestResponse
phonetelephone number++
namefriendly name+ 
toforward all inbound messages to:
'0' = Disable, '1' = E-mail, '2' = URL;
+ 
addressforwarding address+ 
resourceused resource++
resolution'ok' or 'failed' with some error message  +

autorenew

Auto-renew On/Off functionality.

PropertyDescriptionRequestResponse
phonetelephone number++
autorenewauto-renew:
'0' = On, '1' = Off;
++
resourceused resource++
resolution'ok' or 'failed' with some error message  +

plan

Set another operating plan.

PropertyDescriptionRequestResponse
phonetelephone number++
planthe ID of operating plan++
resourceused resource++
resolution'ok' or 'failed' with some error message  +

restore

To restore particular number.

PropertyDescriptionRequestResponse
phonetelephone number++
resourceused resource++
resolution'ok' or 'failed' with some error message  +

cancel

To cancel the subscription for a particular number.

PropertyDescriptionRequestResponse
phonetelephone number++
resourceused resource++
resolution'ok' or 'failed' with some error message  +

balance

Allows you to request current balance.

PropertyDescriptionRequestResponse
balanceaccount current balance +
resourceused resource++
resolution'ok' or 'failed' with some error message  +

The system returns any comments and search results within response property.

Webhook

Use Webhooks to be notified about events that happen with numbers under an account.

Properties user and token are also included for more security.

You can configure Webhook URL on the page of API Settings.

PropertyDescription  
actionevents that happen with number:
'plan setup', 'plan auto renew', 'plan cancelation', 'plan restoration';
  
phonetelephone number  
datedate and time (MST)  
resolution'pending', 'done', 'failed';  
PHP LISTENER EXAMPLE

$obj = json_decode(file_get_contents('php://input'), true);

$user = $obj[user];
$token = $obj[token];
$action = $obj[action];
$phone = $obj[phone];
$date = $obj[date];
$resolution = $obj[resolution];

if (($user == "xxxxx") AND ($token == "yyyyy")) { 

	// Some actions

} else {

	die;

}
EXAMPLE REPORT

{
	"user": "xxxxx",
	"token": "yyyyy",
	"action": "Plan Setup",
	"resolution": "done",
	"phone": "447500000000",
	"date": "2024-03-18 20:11:11"
} 

Receive SMS

Once you've set a script URL for inbound message forwarding, our system will send an HTTP request right upon receiving an SMS with the following strings.

PropertyDescription  
tothe receiver's phone number  
fromthe sender's phone number  
textthe body of the message  
idthe ID of the message in our network  
tokenyour authentication token  
PHP LISTENER EXAMPLE

$obj = json_decode(file_get_contents('php://input'), true);

$to = $obj[to];
$from = $obj[from];
$text = $obj[text];
$token = $obj[token];
if ($token == "abc12345") { 

	// Some actions

} else {

	die;

}
EXAMPLE REPORT

{
	"to": "447500000001",
	"from": "447500000002",
	"text": "Test message",
	"id": "1234567890",
	"token": "abc12345",
}