Number Blocking

Number Blocking stops calls before they are placed or delivered, with two kinds of rules. Destination rules block a whole call class of the account's rate plan (a country, a number range or a service type, identified by a dial-prefix mask) for some or all extensions; they are the /v2/calls-block-unblock family and need an account admin. Blocked numbers block one phone number, inbound and/or outbound, for the whole account; they are /v3/number-blocking. The neighbouring Blacklist Numbers group is not about calls: it is the messaging block list, described at the end of this guide.

Workflow (what the portal does)#

1. Destination rules: GET /v2/calls-block-unblock with page and perPage (both required; perPage is 15, 25, 50, 100 or -1), sort (name by default, -name for descending), filter[sSearch] (a substring of the destination name or of its prefix mask) and extension (comma-separated extension numbers; the status of each destination is then computed for those extensions only, otherwise for every extension of the account). The answer is DataTables-shaped: aaData[] rows with class_id (one or more comma-separated destination ids that share a name), class_name, class_mask (the dialled-prefix pattern, such as ^00) and blocked, which is 1 when blocked for every extension considered, 0 when allowed and -1 when blocked for some of them; iTotalRecords and iTotalDisplayRecords carry the total.
2. Block or unblock: POST /v2/calls-block-unblock with action (0 to block, 1 to unblock), extensions (comma-separated extension numbers, each of which must exist on the account) and destinations (comma-separated class_id values from the list; pass a row's whole class_id string). Both are optional and the four combinations differ: both filled applies the action to those destinations for those extensions; destinations alone to those destinations for every extension; extensions alone to every destination for those extensions; neither to every destination for every extension, that is, block all or unblock all. The answer is 204; read the list again to see the resulting status.
3. Copy rules between extensions is a portal action (Call Blocking → Copy rules); through the API, create the same rules on each extension.
4. Blocked numbers: GET /v3/number-blocking with page and perPage (both required; 15, 25, 50 or 100), filter[search] (a substring of the number or of the notes) and sort (phone_number by default, inbound, outbound or notes, - for descending). A standard paginated answer: data[] rows of {"entry_id", "phone_number", "inbound", "outbound", "notes"} with links and meta (total, per_page, current_page, last_page).
5. Add a blocked number: POST /v3/number-blocking with phone_number (up to 20 characters, unique within the account), inbound and outbound (booleans: refuse calls from the number, refuse calls to it) and optional notes. The answer is 204 with no body: list again to learn the entry_id.
6. Edit or remove: PUT /v3/number-blocking/{entryId} takes the same fields as the create (phone_number is required again; a flag you leave out keeps its value) and DELETE /v3/number-blocking/{entryId} removes the entry. Both answer 204; an id that does not belong to the account answers 404.

Blacklist Numbers#

The Blacklist Numbers group is the account's messaging block list, not a call rule: a number on it is never sent an SMS, MMS or WhatsApp message by the account. A send to it is created with status 4 (failed), error_code BLOCKED and the description Recipient is blocked or opted out (see Conversations), and the number shows sms_blocked: true on a contact's phones in Contacts. Calls are not affected; use the blocked numbers above for that. GET /v3/blacklist-numbers lists the manually blocked numbers as {"id", "mobile_number", "account", "status", "notes", "entrydate"}; POST /v3/blacklist-numbers with mobile_number (up to 20 characters) and optional notes (up to 50) answers 201 with the row, or 204 when it was already blocked; GET /v3/blacklist-numbers/{mobileNumber} answers the row, or 204 when the number is not blocked; DELETE /v3/blacklist-numbers/{mobileNumber} unblocks it (204). status is 2 for a number blocked through this endpoint and 3 for a number that opted out of the account's messages; only 2 rows are listed, shown and deleted here, but both stop sends, and a POST for an opted-out number turns it into a 2 row.

Roles and access#

• The destination rules (list, block or unblock) need an account admin; other users get 403.
• Blocked numbers (/v3/number-blocking) and the blacklist (/v3/blacklist-numbers) are open to any authenticated user of the account.

Pitfalls#

• action is the opposite of what the name suggests: 0 blocks, 1 unblocks.
• There is no all keyword on the block call: extensions=all answers 422 with One or more extensions are invalid., and destinations has no such value either. Leave the field out, or send it empty, to mean "all".
• blocked in the list is an integer, not a boolean, and -1 (partially blocked) appears whenever only some of the extensions considered are blocked. Pass extension to get the answer for specific extensions.
• A row's class_id can hold several ids (12,13). Send that whole string in destinations; the ids grouped under one name are one destination to the portal.
• Both lists require page and perPage (422 without them); an unknown filter[...] or sort answers 400. The /v3/number-blocking list has no -1 page size.
• POST /v3/number-blocking returns no id, and inbound and outbound you leave out are stored as null, not false: send both flags explicitly.
• phone_number on /v3/number-blocking is stored exactly as sent and the uniqueness check is an exact string match, so +353861234567 and 00353861234567 are two entries. Use one format consistently.
• Blacklist a number as 00 followed by the country code and number (00353861234567): that is the form the send-time check compares against. A copy with a + or in national format is listed but may not stop the send.
• GET /v3/blacklist-numbers/{mobileNumber} and the delete ignore opted-out rows (status 3): the check answers 204 for them and the delete leaves them in place.