Maskyoo VMS API

How to place automated voice calls, manage prompt recordings and retrieve call records from your Maskyoo VMS system over HTTP.

Property	Value
Edition	September 2026
Transport	HTTPS
Response format	XML
Base URL	https://dialer2.maskyoo.com/{system_name}/api/?service={service}
Authentication	Authorization: Bearer {api_token}
Request body	application/x-www-form-urlencoded or multipart/form-data

Introduction

The Maskyoo VMS API is a REST-style HTTP API for basic management of your Voice Messaging System (VMS) from your own software. It lets you place outbound voice calls that play recorded or synthesised messages and collect keypad responses, upload and remove the prompt recordings those calls use, and query the call detail records the system keeps for every call. Typical uses are appointment reminders, payment notices, emergency broadcasts and two-way confirmations driven from a CRM, ERP or scheduling application.

The API is exposed at a single HTTPS endpoint per system. Each request names an operation with the service parameter and passes its arguments as ordinary HTTP form fields, either in the URL query string or in a form-encoded POST body. Responses are small XML documents. Any HTTP client library can use the API; no SDK is required. This section gives working examples for the command line (cURL), PHP and C#.

{system_name} in every URL is the identifier of your VMS system, as shown in the address bar when you are logged in to the web interface, for example dialer_acme.

Services

Service	Purpose	Methods	Success status
makecall	Place an outbound call that plays up to 15 prompts, collects keypad digits and can transfer to a live phone	GET, POST	Ok
upload_prompt	Upload an audio file for use as a prompt	POST multipart	OK
delete_prompt	Remove an uploaded prompt	GET, POST	OK
cdrquery	Retrieve call detail records with a SELECT query	GET	rows

Conventions used by this API

• GET and POST are interchangeable for every service except cdrquery, which reads its parameter from the query string only, and upload_prompt, which needs a multipart POST for the file.
• JSON request bodies are not supported. Send parameters as form fields. A JSON body is ignored and the request fails as if the parameters were missing.
• The HTTP status is always 200. Success and failure are signalled in the response body: XML with a status element on success or a handled error, plain text for authentication and validation failures. See Handling responses below.
• Text must be URL-encoded UTF-8. Plain-text prompts, Hebrew included, must be URL-encoded. HTTP libraries do this automatically for form fields; hand-built query strings must be encoded explicitly.

Getting started

Three things must be in place before your first request succeeds. Each is checked on every call, in this order, and a failing check returns the plain-text message shown in Response messages.

1. Register your server IP. Only addresses on your system's API allow list may call the API. Ask Maskyoo support to add the public IP addresses of your servers.
2. Create an API token. In the web interface: Users › Manage users › Edit API user › Security tab › Copy code. Send it as a Bearer token on every request.
3. Keep credit on the account. Requests are refused while the account balance is zero. Calls and text-to-speech consume credit.

The token travels in the standard Authorization header. Treat it like a password: it grants the right to place calls billed to your account.

Authorization: Bearer 3f9c2a1e7b4d…

note

This token is the VMS system token, taken from the API user's Security tab in the VMS web interface. It is not the Maskyoo platform token described in Adding a Maskyoo API access token.

Your first call

This request calls 052-345-6789, presents 055-432-1987 as the caller, and reads the text aloud with the text-to-speech engine. cURL's --data-urlencode takes care of URL-encoding the Hebrew text. Replace the system name, token and numbers with your own.

Request

curl -X POST "https://dialer2.maskyoo.com/{system_name}/api/?service=makecall" \
  -H "Authorization: Bearer 3f9c2a1e7b4d…" \
  --data-urlencode "destination=0523456789" \
  --data-urlencode "caller_id=0554321987" \
  --data-urlencode "playfile1=שלום, זוהי הודעת בדיקה ממערכת ההודעות הקוליות"

Response — HTTP 200, success

<?xml version="1.0"?>
<root>
  <service>makecall</service>
  <status>Ok</status>
</root>

Handling responses

Because every response arrives with HTTP status 200, your client must decide success or failure from the body. The reliable procedure is the one used in all the examples in this section:

1. Empty body: the request failed. This only happens for upload_prompt when the audio could not be converted, and for an unrecognised service value.
2. Body does not start with <: a plain-text error. Authentication and parameter-validation failures use this form. Log the text; it is meant to be read by a developer.
3. Body is XML with a status element: compare it case-insensitively with Ok. On Error, the description element explains why. The XML declaration is present on success and absent on some errors, so do not rely on it.
4. Body is XML without status: a cdrquery result set. Iterate the row elements.

Successful makecall responses do not include the destination or a message element; correlate calls by the private_field values you sent, which come back with the call result and in the call records.

The complete list of bodies the API returns, grouped by service, is in Response messages.

ראו גם

• ביצוע שיחה — makecall
• העלאת הקלטה — upload_prompt
• מחיקת הקלטה — delete_prompt
• שאילתות CDR — cdrquery
• הודעות תגובה
• הוספת טוקן API

---

This document contains proprietary and confidential material of Maskyoo Ltd. Any unauthorized reproduction, use, or disclosure of this material, or any part thereof, is strictly prohibited. This document is solely for the use of Maskyoo employees and authorized Maskyoo customers. © 2014–2026 Maskyoo Ltd. All rights reserved.