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.
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-12-02 15:51:18" }
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", }