Maskyoo Management

Services for creating, updating, releasing, restoring and allocating Maskyoo numbers, and for placing calls on them.

Important

Allocating (create_maskyoo), releasing (release_maskyoo) and restoring (restore_maskyoo) numbers may affect your rates according to your commercial plan.

get_maskyoo

Get the details of the Maskyoo numbers in the account, including call destinations, working hours, private fields, recording percentage, number exposure and more.

Endpoint: /api/?service=get_maskyoo

Parameters

Parameter	Type	Required	Description
`maskyoo`	string	NO	A specific Maskyoo number. When sent, only that number is returned.
`status`	int	NO	`1` = active numbers only (default) / `0` = suspended numbers.
`page`	int	NO	Page number (default `0`).
`limit`	int	NO	Rows per page. Defaults to `1000` when the parameter is not sent; sending `0` or a value above `10000` returns up to `10000` rows.
`filter_name`	string	NO	Field name to filter by (for example `description`, `private_field1`, `email`, `extenstion`). Requires `filter_value` as well.
`filter_value`	string	NO	The filter value.
`filter_operator`	string	NO	`EQ` (default), `NE`, `LT`, `GT`, `LIKE`.
`format`	string	NO	`json` / `xml`.

note

The limit, page and status parameters apply to a general request only — without a specific maskyoo and without a filter. When maskyoo or filter_name/filter_value is sent, all matching rows are returned without pagination.

Response fields

description, maskyoo, maskyoo_old (only when the two-number feature is enabled for the account), active_status, create_time, email, private_field1..10, sms_destination_phone, working_hours, out_of_time_destination_phone, callback_url, callback_url_option, greeting_in, ringback_tone, greeting_out, call_destination_phone, dial_option, dial_timeout_in_sec, record_percentage, record_option, extenstion, expose, disallow_callback, default_dest.

Error codes

Code	Description
`4030`	`filter_name` is not valid
`4031`	No results

Example

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

get_available_maskyoo

Return the list of numbers that are available for allocation (it does not allocate — it only returns).

Endpoint: /api/?service=get_available_maskyoo

Parameters

Parameter	Type	Required	Description
`prefix`	string	NO	Prefix used to filter the available numbers.
`maskyoo`	string	NO	Part of a Maskyoo number to filter by (an alternative to `prefix`).
`amount`	int	NO	Number of results to return (default `5`, maximum `50`).
`format`	string	NO	`json` / `xml`.

Error codes

Code	Description
`4050`	No available numbers
`4051`	No available numbers with the requested prefix

create_maskyoo

Create and allocate a new Maskyoo number to the account, with all of its dialing, prompt, recording and callback attributes.

Endpoint: /api/?service=create_maskyoo

Parameters

Parameter	Type	Required	Description
`description`	string	YES	The number description (up to 199 characters).
`call_destination_phone`	string	YES	Destination numbers to dial, comma separated (maximum 150 characters).
`maskyoo`	string	NO	A specific Maskyoo number to request (otherwise one is allocated automatically).
`prefix`	string	NO	Prefix used for automatic number selection.
`active_status`	int	NO	`1` = active (default), `0` = suspended.
`dial_option`	int/string	NO	`1` / `,` = simultaneous dialing (default), `2` / `;` = sequential (hunt), `3` / `IVR` = call router.
`dial_timeout_in_sec`	int	NO	`1–180` seconds (the default comes from the account settings).
`record_option`	int	NO	Who hears the "this call is being recorded" announcement: `1` = the caller, `2` = the answering party, `3` = both. Applies only while recording is enabled — whether the call is recorded at all (yes/no/percentage) is controlled by the separate `record_percentage` field.
`record_percentage`	int	NO	Recording percentage `0–100` (`0` = no recording; the alternative name `record_presantge` is also accepted).
`expose`	int	NO	`1` = present the Maskyoo number (default), `2` = present the caller, `3` = anonymous.
`disallow_callback`	int	NO	`0` (allowed), `1` or `2` (blocked according to the account settings).
`callback_url`	string	NO	Callback URL (up to 511 characters).
`callback_url_option`	int	NO	`1` = at call start, `2` = at call end (default), `3` = both.
`greeting_in`	string	NO	Internal prompt name.
`greeting_out`	string	NO	Prompt name played to the caller.
`ringback_tone`	string	NO	Ringback tone (file name).
`email`	string	NO	Email address for notifications.
`sms_destination_phone`	string	NO	Number(s) that receive SMS notifications.
`working_hours`	string	NO	A weekly working-hours pattern (168 characters). A string shorter than 168 characters is silently rejected — the value is not saved and no error is returned.
`out_of_time_destination_phone`	string	NO	Alternative destination outside working hours.
`private_field1` … `private_field10`	string	NO	Private fields (up to 254 characters each).
`format`	string	NO	`json` / `xml`.

Response

On success the full object of the created number is returned — in the same structure that get_maskyoo returns.

Main error codes

Code	Description
`4000`	`description` is empty or longer than 199
`4001`	`call_destination_phone` is empty / invalid / longer than 150
`4002-4006`	`private_field1..10` longer than 254
`4007`	`callback_url` longer than 511
`4008-4009`	Allocating the Maskyoo number failed
`40010`	`callback_url_option` out of the range 1–3
`40011`	`dial_option` out of the range 1–3
`40012`	`record_option` out of the range 1–3
`40013`	`dial_timeout_in_sec` out of the range 1–180
`40014`	`expose` out of the range 1–3
`40015`	`disallow_callback` is not 0/1/2

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/?service=create_maskyoo" \
     -d "description=Main office" \
     -d "call_destination_phone=972544224422,972544224423" \
     -d "dial_option=1" \
     -d "record_percentage=100" \
     -d "record_option=2" \
     -d "format=json"

update_maskyoo

Update the attributes of an existing Maskyoo number. The number must belong to the account (otherwise error 4019 is returned).

Endpoint: /api/?service=update_maskyoo

Parameters

Identical to create_maskyoo, where:

Required: maskyoo, description, call_destination_phone. call_destination_phone must be sent in every update request (even when you only want to change another field) — otherwise error 4012 is returned.
All other parameters are optional; only the values that are sent are updated.

Response

On success the full object of the number after the update is returned — in the same structure that get_maskyoo returns.

Main error codes

Code	Description
`4010`	`description` is empty or longer than 199
`4011`	`maskyoo` is empty / shorter than 5
`4012`	`call_destination_phone` is invalid or longer than 150
`4013-4017`	`private_field1..10` longer than 254
`4018`	Invalid Maskyoo number
`4019`	The Maskyoo number does not exist in the account
`4020` / `4021`	The update failed
`4022-4027`	Invalid `callback_url_option` / `dial_option` / `record_option` / `dial_timeout_in_sec` / `expose` / `disallow_callback` values

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/?service=update_maskyoo" \
     -d "maskyoo=972776670000" \
     -d "description=Updated" \
     -d "call_destination_phone=972544224422" \
     -d "record_percentage=50" \
     -d "format=json"

release_maskyoo

Release a Maskyoo number from the account. The number returns to the pool of available numbers.

Endpoint: /api/?service=release_maskyoo

Parameters

Parameter	Type	Required	Description
`maskyoo`	string	YES	The number to release (in accounts with a secondary Maskyoo number, the old number is supported as well).
`format`	string	NO	`json` / `xml`.

On release the system usually also removes the per-Maskyoo blocks of that number, but in some configurations those blocks may remain — it is therefore recommended to verify and manage blocks through the blacklist services. Global blacklist blocks always remain.

Error codes

Code	Description
`4040`	`maskyoo` is missing
`4041`	The Maskyoo number does not exist
`4042`	The release failed
`4043`	Invalid Maskyoo number

restore_maskyoo

Restore a Maskyoo number that was released. It works only on a number that previously belonged to the current account, and only while that number is still free and has not been re-allocated.

Endpoint: /api/?service=restore_maskyoo

Parameters

Parameter	Type	Required	Description
`maskyoo`	string	YES	The number to restore.
`format`	string	NO	`json` / `xml`.

Error codes

Code	Description
`4040`	`maskyoo` is missing
`4041`	Invalid number
`4042`	The number is not registered as released from the account
`4043`	The number is already active
`4044`	The number cannot be restored to the account

In case of any other failure a detailed status code is returned to help when contacting support.

create_maskyoo_call

Initiate a call (classic Click2Call): the system calls the destination and, on answer, connects it to the Maskyoo number.

Endpoint: /api/?service=create_maskyoo_call

Parameters

Parameter	Type	Required	Description
`maskyoo`	string	YES	The number the call is "sent" from.
`destination`	string	YES	The calling number.
`first_target`	string	NO	`maskyoo` to call the Maskyoo number first and then connect it to the destination (this also swaps `greeting_in` / `greeting_out`).
`format`	string	NO	`json` / `xml`.

Error codes

Code	Description
`3011`	`maskyoo` is empty / invalid
`3012`	Calls cannot be placed for this account
`3013`	The destination is blacklisted
`3014`	The Maskyoo number is suspended
`3015`	Placing the call failed
`3016`	The Maskyoo number does not exist

create_maskyoo_call_v2

Initiate a call with two number pairs — each side is presented with a different Caller ID. This version also accepts custom parameters that are stored on the call for reporting and for the pixel.

Endpoint: /api/?service=create_maskyoo_call_v2

Parameters

Parameter	Type	Required	Description
`maskyoo1` (or `maskyoo`)	string	YES	Caller ID for the first side.
`destination1`	string	YES	The number the call goes out to.
`maskyoo2`	string	NO	Caller ID for the second side (default: same as `maskyoo1`).
`destination2`	string	YES	The number the first side is connected to.
Additional parameters	string	NO	Any additional parameter is stored on the call and is available in the reports and in the pixel.
`format`	string	NO	`json` / `xml`.

Error codes

Code	Description
`3031`	`maskyoo` is empty / invalid
`3032`	`destination1` or `destination2` is empty / invalid
`3033` / `3038`	destination1 / destination2 is blacklisted
`3034` / `3037`	maskyoo1 / maskyoo2 is suspended
`3035`	Placing the call failed
`3036`	maskyoo1 or maskyoo2 does not exist
`3039`	Outside the working hours of one of the numbers

click2call_link

Service disabled (deprecated)

The service still generates a signed link, but placing the call when the link is opened is currently disabled — clicking the link does not initiate a call. Do not rely on these links in business processes; for details contact Maskyoo support.

Create a signed link that can be embedded in a website or a campaign. When enabled, opening the link initiates a call according to the settings.

Endpoint: /api/?service=click2call_link

Parameters

Parameter	Type	Required	Description
`maskyoo`	string	YES	The Maskyoo number presented to the destination.
`destination`	string	YES	The destination.
`first_target`	string	NO	`maskyoo` / `destination` (default).
`expire_days`	int	NO	Link validity in days (default `365`).
`format`	string	NO	`json` / `xml`.

Response

result contains the public URL of the generated link (including the signature and the expiration date).

Error codes

Code	Description
`3017`	`maskyoo` is empty / invalid
`3018`	`destination` is empty / invalid
`3019`	The Maskyoo number does not exist
`3020`	The Maskyoo number is suspended
`3021`	The destination is blacklisted

test

Check API availability. It requires no additional parameters, but it does require a valid IP and token.

Endpoint: /api/?service=test

Returns {"service":"test","status":{"code":200,"description":"OK"}}.

System impact

The Maskyoo management services affect the number itself and all the logic that depends on it:

Number management screen — create / update / release / restore is visible immediately in the number management page and in all reports
Billing — allocation (create_maskyoo) and release / restore may affect the monthly rate according to the commercial plan
Blacklist — releasing a number usually removes the blocks defined for that Maskyoo number (in some configurations they may remain — it is recommended to verify through the blacklist services); global blocks are kept
Click2Call — click2call_link creates a signed public URL valid for expire_days; placing the call from the link is currently disabled (see the warning in that section)
Calls and reports — create_maskyoo_call / create_maskyoo_call_v2 create a live call that is written to the CDR with all custom parameters, and it takes part in automation and in the pixel
Changes log — every change to a number is recorded and presented in the Maskyoo changes log

get_maskyoo​

Parameters​

Response fields​

Error codes​

Example​

get_available_maskyoo​

Parameters​

Error codes​

create_maskyoo​

Parameters​

Response​

Main error codes​

Example​

update_maskyoo​

Parameters​

Response​

Main error codes​

Example​

release_maskyoo​

Parameters​

Error codes​

restore_maskyoo​

Parameters​

Error codes​

create_maskyoo_call​

Parameters​

Error codes​

create_maskyoo_call_v2​

Parameters​

Error codes​

click2call_link​

Parameters​

Response​

Error codes​

test​

System impact​

See also​

get_maskyoo

Parameters

Response fields

Error codes

Example

get_available_maskyoo

Parameters

Error codes

create_maskyoo

Parameters

Response

Main error codes

Example

update_maskyoo

Parameters

Response

Main error codes

Example

release_maskyoo

Parameters

Error codes

restore_maskyoo

Parameters

Error codes

create_maskyoo_call

Parameters

Error codes

create_maskyoo_call_v2

Parameters

Error codes

click2call_link

Parameters

Response

Error codes

test

System impact

See also