Maskyoo REST API

The Maskyoo REST API provides programmatic access to Maskyoo numbers, users, tags, the blacklist, call recordings, voice prompts, CDR queries and Google Ads offline conversions.

Rest API URL

All REST API requests should be sent to the following URL:

https://[MASKYOO_URL]/api/

Every function is called by passing the service name in the query string or in the POST body (for example service=get_maskyoo). Parameters may be sent as GET or POST; file uploads require multipart/form-data.

Public Click2Call links (generated by click2call_link) are returned as a full URL. Note that placing the call from the link is currently disabled (see Maskyoo Management).

Authentication

Every request must pass two authentication layers on the server:

1. IP restriction

The client IP address must appear in the account's allowed IP list (configured in the interface under System Settings → Settings → API Settings tab). A request from an unauthorized IP returns HTTP 401 Unauthorized - IP Address:'…' is not allowed.

2. Bearer token

If an API access token is configured for the account, it must be sent in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

A missing token returns 401 Unauthorized - Token Required; an expired token returns 401 Unauthorized - Token Expired; a token that does not belong to the system returns 401 Unauthorized - Invalid Token.

For details about creating a token see Adding an API access token.

cURL example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X GET "https://[MASKYOO_URL]/api/?service=get_maskyoo&maskyoo=0776670000&format=json"

Request format

All services accept both GET and POST with the same parameters. Uploads (upload_prompt) require multipart/form-data.

GET request

https://[MASKYOO_URL]/api/?service=SERVICE_NAME&param1=value1&param2=value2

POST request

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/" \
     -d "service=SERVICE_NAME" \
     -d "param1=value1"

Response format

The format parameter controls the output format:

Value	Description
json	JSON response
xml	XML response (the default when json is not specified)

General response structure:

{
  "service": "get_maskyoo",
  "status": { "code": 200, "description": "ok" },
  "result": [ ... ]
}

• service – the name of the service that was called.
• status.code – 200 on success, otherwise a service specific error code (see each function).
• status.description – a textual explanation.
• result – depends on the service: an object, an array of objects, or a free-form string.

Services

service=<service_name>

Service name	Description
get_maskyoo	Get the full settings of one or more Maskyoo numbers
get_available_maskyoo	Get the numbers available for allocation
create_maskyoo	Allocate and configure a new Maskyoo number
update_maskyoo	Update the settings of an existing Maskyoo number
release_maskyoo	Release a Maskyoo number from the account
restore_maskyoo	Restore a released Maskyoo number
create_maskyoo_call	Place an outbound call between two numbers
create_maskyoo_call_v2	Place an outbound call (extended version)
click2call_link	Create a public Click2Call link
cdr_query	Query call data (CDR) with a read-only SQL statement
cdr_subunique_query	Aggregated report of answered calls per unique caller
get_record_by_call_uuid	Download the call recording of a single call
get_cdr_metadata_by_call_uuid	Get the marketing metadata of a single call
create_maskyoo_cdr	Create a manual call record
get_google_ads_offline_conversion	Get calls waiting to be reported to Google Ads
set_google_ads_offline_conversion	Report an offline conversion back to Maskyoo
get_users	Get the list of account users
get_user_by_id	Get a single user by ID
set_user	Create a new user
update_user	Update an existing user
delete_user	Delete a user
set_ddi_to_user	Assign Maskyoo numbers to a user
get_ddi_by_user_id	Get the Maskyoo numbers assigned to a user
delete_ddi_from_user_id	Remove a Maskyoo number from a user
get_users_access_log	Get the users access log
view_tags	Get tags by name (alias of view_tag_by_name)
view_tag_by_id	Get a single tag by ID
view_tag_by_name	Get tags by name
view_tags_by_maskyoo	Get the tags of a specific Maskyoo number
create_tag	Create a new tag
update_tag	Rename an existing tag
delete_tag	Delete a tag
add_member_to_tag	Add a Maskyoo number to a tag
remove_member_from_tag_id	Remove a Maskyoo number from a tag by tag ID
remove_member_from_tag_name	Remove a Maskyoo number from a tag by tag name
view_maskyoo_members_by_tag_id	Get the Maskyoo numbers of a tag by tag ID
get_members_by_tag_id	Get the members of a tag by tag ID
get_members_by_tag_name	Get the members of a tag by tag name
get_blacklist	Get the blocked numbers of the account
add_number_to_blacklist	Block a number (globally or for one Maskyoo number)
remove_number_from_blacklist	Unblock a number
get_prompts_list	Get the list of voice prompts in the account
download_prompt	Download a voice prompt file
upload_prompt	Upload a new voice prompt
delete_prompt	Delete a voice prompt
recording_studio	Record a prompt from the phone
test	Connectivity and authentication check

API categories

Category	Description	Services
Maskyoo Management	Create, update, release, restore, allocate, calls and Click2Call links	10
User Management	Users, permissions, Maskyoo number assignment, access log	9
Tag Management	Create / update / delete tags and assign Maskyoo numbers to them	13
Queries & Recordings	CDR queries, recording download, metadata, Google Ads offline conversions, manual CDR	7
Blacklist	Manage blocked numbers (global block or per Maskyoo number)	3
Voice Prompts	Upload, download, delete, list and record from the phone	5

Code examples

PHP

<?php
$base_url = "https://[MASKYOO_URL]/api/";
$token    = "YOUR_TOKEN_HERE";

$data = array(
    "service" => "get_maskyoo",
    "maskyoo" => "0776670000",
    "format"  => "json",
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $base_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer " . $token,
));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

C#

using System.Net;
using System.Collections.Specialized;
using System.Text;

string url   = "https://[MASKYOO_URL]/api/";
string token = "YOUR_TOKEN_HERE";

using (var client = new WebClient())
{
    var values = new NameValueCollection();
    values["service"] = "get_maskyoo";
    values["maskyoo"] = "0776670000";
    values["format"]  = "json";

    client.Headers.Add("Authorization", "Bearer " + token);
    var response       = client.UploadValues(url, values);
    var responseString = Encoding.UTF8.GetString(response);

    Console.WriteLine(responseString);
}

General error codes

Code	Meaning
200	Success
401	Authentication failure (unauthorized IP / missing, expired or invalid token / suspended account)
998	Missing service parameter
999	Internal error

Every service returns additional service specific error codes (for example 1xxx for CDR, 2xxx for the blacklist, 3xxx for calls, 4xxx for Maskyoo numbers, 5xxx for tags, 6xxx for the access log, 7xxx-8xxx for users, 9xxx for voice prompts). Details appear in each service.

Limits and timeouts

• A single request may run for up to 10 minutes (mainly relevant to heavy cdr_query statements and to recordings fetched from the archive).
• upload_prompt: up to 50 MB per file.
• A suspended account may not use the API (returns 401 Unauthorized - Account Suspended).

Support

For questions and issues please contact Maskyoo support.

System impact

The REST API is a full programmatic work channel on the account:

• User interface — every change made through the API (creating a number, updating a user, adding to the blacklist) is visible immediately in the Maskyoo interface, and all changes are written to the changes log
• Permissions — the token is bound to a specific user and works under that user's permissions; unauthorized calls are rejected
• Performance — heavy cdr_query statements may run for up to 10 minutes; use filters and LIMIT to avoid overloading
• Automation — creating a manual CDR (create_maskyoo_cdr) immediately triggers the end-of-call automation rules and the pixel
• Security — both an IP whitelist and a Bearer token are required; a suspended account cannot use the API

See also

• Adding an API access token
• Maskyoo Management
• User Management
• CDR Queries
• SMS Gateway API