Guide: Managing Blocked Numbers with NetSapiens API V2

Call blocking on the NetSapiens platform

This guide explains how to manage blocked numbers through the NetSapiens API V2, specifically covering how to block numbers and retrieve lists of blocked numbers. This can be particularly useful for VOIP platforms with shared voicemail box features. Along with the obvious benefit of allowing users to manage blocked callers pursuant to regulations under the TCPA, the flexibility of the platform in managing these block actions is a valuable tool for cost management and increasing efficiency.

Authentication

Get an access token:

curl -X POST "https://api.netsapiens.com/oauth/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=subscriber"

Blocking a Number

Block a number for a specific user:

curl -X POST "https://api.netsapiens.com/ns-api/v2/users/1001/blocked_numbers"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"
-d '{"phone_number":"+15551234567","description":"Blocked caller"}'

Block a number for an entire domain:

curl -X POST "https://api.netsapiens.com/ns-api/v2/domains/example.com/blocked_numbers"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"
-d '{"phone_number":"+15551234567","description":"Domain-wide block"}'

NOTE: Adding more than one blocked number for a user at a time

Another method to add blocked numbers on a user basis is to use the #Update a Answerrule for a User endpoint, which can be found in the documentation here:

https://docs.ns-api.com/reference/put_domains-domain-users-user-answerrules-timeframe

An example of the parameter in this case is as follows:

"phone-numbers-to-reject": {

    "enabled": "yes",

    "remove": "no",

    "parameters": [

      "[phone number]",

      "[phone number]"

    ]

  },

Retrieving Blocked Numbers

⚠️

NOTE: Pagination and lists larger than 500 item Portal limit

For those seeking a means to output a larger or even complete list of blocked numbers, the following API calls will return results based on the pagination settings provided when making the call.

To be clear, this is a means to bypass the soft 500 results limit in the Portal. For more information on how pagination works with the NS API, please see the following guide:

https://docs.ns-api.com/docs/pagination-and-api-data

Get blocked numbers for a user:

curl -X GET "https://api.netsapiens.com/ns-api/v2/users/1001/blocked_numbers"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"

Get blocked numbers for a domain:

curl -X GET "https://api.netsapiens.com/ns-api/v2/domains/example.com/blocked_numbers"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"

Unblocking a Number

Unblock a number for a user:

curl -X DELETE "https://api.netsapiens.com/ns-api/v2/users/1001/blocked_numbers/12345"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"

Unblock a number for a domain:

curl -X DELETE "https://api.netsapiens.com/ns-api/v2/domains/example.com/blocked_numbers/12345"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"

General Tips

1. Replace YOUR_ACCESS_TOKEN with the token received from the authentication request
2. Replace 1001 with the actual user extension
3. Replace example.com with your actual domain name
4. Replace 12345 with the actual ID of the blocked number (obtained from the GET request)
5. For better JSON output, pipe the response through jq:
   curl -X GET "https://api.netsapiens.com/ns-api/v2/users/1001/blocked_numbers"
   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" | jq
6. For troubleshooting, add the -v flag to see verbose output:
   curl -v -X GET "https://api.netsapiens.com/ns-api/v2/users/1001/blocked_numbers"
   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"