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
plans
activate
list
settings
update
autorenew
plan
restore
cancel
balance

search

Search for available phone numbers.

Property	Description	Request	Response
pid	the ID of this phone number		+
phone	an available telephone number The '' character will match any digits.*	+	+
carrier	the name of network		+
country	the ISO country code of this phone number	+	+
resource	used 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.

Property	Description	Request	Response
country	the ISO country code of this phone number	+	+
plan	the ID of this operating plan		+
title	the plan title		+
days	billing cycle in days		+
setup	the setup fee		+
renew	the renewal fee		+
premium	the plan is available with a premium account		+
resource	used 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.

Property	Description	Request	Response
pid	the ID of this phone number	+	+
plan	the ID of operating plan	+	+
phone	telephone number		+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

list

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

Property	Description	Request	Response
phone	telephone number The '' character will match any digits.*	+	+
status	the status of number '1' = Allocation, '2' = Live, '3' = Released, '4' = Storage;	+	+
country	the ISO country code of this phone number	+	+
expires	date of auto renew or expiration (MST)		+
autorenew	auto-renew: '0' = On, '1' = Off;	+	+
plan	the ID of operating plan		+
pages	a total number of pages 10 numbers per page		+
page	current page	+	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

settings

Number settings.

Property	Description	Request	Response
phone	telephone number	+	+
country	country		+
name	friendly name		+
expires	date of auto renew or expiration (MST)		+
plan	the ID of operating plan		+
fee	the renewal fee		+
autorenew	auto-renew: '0' = On, '1' = Off;		+
to	forward all inbound messages to: '0' = Disable, '1' = E-mail, '2' = URL;		+
address	forwarding address		+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

update

Update phone number properties.

Property	Description	Request	Response
phone	telephone number	+	+
name	friendly name	+
to	forward all inbound messages to: '0' = Disable, '1' = E-mail, '2' = URL;	+
address	forwarding address	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

autorenew

Auto-renew On/Off functionality.

Property	Description	Request	Response
phone	telephone number	+	+
autorenew	auto-renew: '0' = On, '1' = Off;	+	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

plan

Set another operating plan.

Property	Description	Request	Response
phone	telephone number	+	+
plan	the ID of operating plan	+	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

restore

To restore particular number.

Property	Description	Request	Response
phone	telephone number	+	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

cancel

To cancel the subscription for a particular number.

Property	Description	Request	Response
phone	telephone number	+	+
resource	used resource	+	+
resolution	'ok' or 'failed' with some error message		+

balance

Allows you to request current balance.

Property	Description	Request	Response
balance	account current balance		+
resource	used 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.

Property	Description
action	events that happen with number: 'plan setup', 'plan auto renew', 'plan cancelation', 'plan restoration';
phone	telephone number
date	date 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-11-20 23:47:35"
}

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.

Property	Description
to	the receiver's phone number
from	the sender's phone number
text	the body of the message
id	the ID of the message in our network
token	your 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",
}