Skip to main content

Add blocked numbers

POST 
/api/v1/blocked-numbers/add

Add numbers to one of your account's two lists of numbers that are skipped when you send to groups:

  • Blocked: numbers that replied STOPP to one of your campaigns, or that were added by hand.
  • Ignored: your own list. It works exactly like the blocked list, except that a number only ends up there when you add it, for example a number that no longer works, so you don't pay to send to it.

Choose the list with type (blocked is the default). A number can be on both lists. Numbers on either list are skipped when you send to groups.

You can add 1 to 100 numbers in one request, as a single string or an array of strings. Each number is handled on its own and ends up in either added or errors, the latter with a reason. Numbers are saved in their international form without a leading +, for example 46700000001. A number without a country code, such as 0700000001, is read with the country of your account. A number that is already on the list you chose is reported as an error and is not added again.

The request succeeds (200, status: success) when at least one number was added, even if others failed, so check errors on a 200 too. Outside test mode it returns 400 with status: failed only when nothing was added. That 400 response then still carries added, errors and warnings, so you can see why each number failed.

Set removeFromContactLists to true to also remove the newly added numbers from every contact list on your account. Numbers that were rejected, for example because they were already on the list, are not touched. If that clean-up fails, the numbers stay added and warnings explains what happened.

Set testMode to true to try a request without changing anything: nothing is saved and no contact lists are touched, but the response shows what would be added and still reports duplicates and invalid numbers. In test mode the request always returns 200, even if nothing would be added; the 400 for "nothing added" does not apply.

Request​

Body

The number to add, or an array of up to 100 of them, and optionally which list to add them to.

    numbers objectrequired

    The number to add, or an array of 1 to 100 numbers. Use the international format (for example +46700000001); a number without a country code is read with the country of your account.

    oneOf
    string
    typestring

    Which list to add the numbers to: blocked (the default) or ignored.

    Possible values: [blocked, ignored]

    Default value: blocked
    removeFromContactListsboolean

    If true, the newly added numbers are also removed from every contact list on your account. Numbers that are rejected, for example because they are already on the list, are not touched. Defaults to false.

    Default value: false
    testModeboolean

    Enables test mode for this request, as a dry run: nothing is saved and no contact lists are touched. The response shows which numbers would be added, and duplicates and invalid numbers are still reported. The request always returns 200 in test mode, even if nothing would be added. Defaults to false.

    Default value: false

Responses​

At least one number was added. Check errors for any numbers that could not be added.