IP Whitelist

The IP Whitelist API allows you to manage IP address whitelists for voice services in Bandwidth's Universal Platform. This functionality enables you to specify which IP addresses should be permitted for voice communication, providing enhanced security and control over your network access.

Overview

The whitelist endpoint supports both retrieving and adding IP addresses through a unified whitelists array structure. This allows you to:

• Retrieve Current Whitelists: Get all currently whitelisted IP addresses for your account
• Voice Services: Whitelist IP addresses for voice communications with proper sub-account and location identifiers
• Account-Level Whitelisting: Whitelist IP addresses at the account level

Validation Rules

Before making requests to the whitelist endpoint, ensure your data meets these requirements:

• Maximum IP Addresses: Up to 10 IP addresses per whitelist entry
• IP Format: Valid IPv4 (no subnet masks)
• Operation: Must be set to 'ADD'
• Whitelist Entries: At least one whitelist entry must be provided
• Service Identifiers: Each entry must include subAccountId and locationId (both as strings for specific configurations, or both as null for account-level whitelisting)
• Account-Level Limitation: Only one whitelist entry may have both subAccountId and locationId as null

Get Whitelist IP Addresses

API Operation

GET https://api.bandwidth.com/api/v2/accounts/{accountId}/whitelists

Retrieve all IP addresses currently whitelisted for your account's voice services configuration. This operation returns the complete whitelist configuration, including all IP addresses organized by their service identifiers. The account-level entry is indicated by no subAccountId and locationId, and represents all whitelisted IP addresses on the account.

Query Parameters

You can filter the whitelist results using the following optional query parameters:

Parameter	Type	Description
ipFilter	string	Filter whitelist entries by specific IP address
subAccountIdFilter	string	Filter whitelist entries by specific sub-account ID
locationIdFilter	string	Filter whitelist entries by specific location ID
showAccountLevel	boolean	Include account-level whitelist entries in response (default: true)

Example with Filters

GET https://api.bandwidth.com/api/v2/accounts/{accountId}/whitelists?subAccountIdFilter=10001&locationIdFilter=100001

Multiple Configurations Response

Example Request

GET https://api.bandwidth.com/api/v2/accounts/12345/whitelists
Authorization: Bearer mySecretToken

Example Request with Filters

GET https://api.bandwidth.com/api/v2/accounts/12345/whitelists?subAccountIdFilter=10001&locationIdFilter=100001
Authorization: Bearer mySecretToken

Example Request Filtering by IP Address

GET https://api.bandwidth.com/api/v2/accounts/12345/whitelists?ipFilter=127.127.127.127
Authorization: Bearer mySecretToken

Example Response

{
  "data": {
    "whitelists": [
      {
        "ipAddresses": [
          "125.125.125.125",
          "125.125.125.126"
        ],
        "subAccountId": "10001",
        "locationId": "100001"
      },
      {
        "ipAddresses": [
          "126.126.126.126",
          "126.126.126.127"
        ],
        "subAccountId": "20002",
        "locationId": "200002"
      },
      {
        "ipAddresses": [
          "125.125.125.125",
          "125.125.125.126",
          "126.126.126.126",
          "126.126.126.127",
          "127.127.127.127",
          "127.127.127.128"
        ]
      }
    ]
  },
  "links": [
    {
      "href": "https://api.bandwidth.com/v2/accounts/12345/whitelists",
      "rel": "self",
      "method": "GET"
    }
  ],
  "errors": []
}

Specific Sub-Account Configurations Response

If you filter by a specific IP, subAccountId, locationId, or set showAccountLevel to false:

Example Response

{
  "data": {
    "whitelists": [
      {
        "ipAddresses": [
          "127.127.127.127",
          "127.127.127.128",
          "127.127.127.129"
        ],
        "subAccountId": "10001",
        "locationId": "100001"
      },
      {
        "ipAddresses": [
          "128.128.128.128",
          "128.128.128.129",
          "128.128.128.130"
        ],
        "subAccountId": "20002",
        "locationId": "200002"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.bandwidth.com/v2/accounts/12345/whitelists",
      "rel": "self",
      "method": "GET"
    }
  ],
  "errors": []
}

Update Whitelist IP Addresses

API Operation

PATCH https://api.bandwidth.com/api/v2/accounts/{accountId}/whitelists

The whitelist operation merges the provided IP addresses with any existing whitelisted addresses for the specified services.

Multiple Configurations

Example Request

PATCH https://api.bandwidth.com/api/v2/accounts/12345/whitelists
Content-Type: application/json
Authorization: Bearer mySecretToken

{
  "operation": "ADD",
  "whitelists": [
    {
      "ipAddresses": [
        "127.127.127.127"
      ],
      "subAccountId": "10001",
      "locationId": "100001"
    },
    {
      "ipAddresses": [
        "128.128.128.128"
      ],
      "subAccountId": "20002",
      "locationId": "200002"
    },
    {
      "ipAddresses": [
        "126.126.126.126"
      ]
    }
  ]
}

Example Response

{
  "data": {
    "operation": "ADD",
    "whitelists": [
      {
        "ipAddresses": [
          "127.127.127.127",
          "127.127.127.128",
          "127.127.127.129"
        ],
        "subAccountId": "10001",
        "locationId": "100001"
      },
      {
        "ipAddresses": [
          "128.128.128.128",
          "128.128.128.129",
          "128.128.128.130"
        ],
        "subAccountId": "20002",
        "locationId": "200002"
      },
      {
        "ipAddresses": [
          "126.126.126.126",
          "126.126.126.127",
          "126.126.126.128",
          "127.127.127.127",
          "127.127.127.128",
          "127.127.127.129",
          "128.128.128.128",
          "128.128.128.129",
          "128.128.128.130"
        ]
      }
    ]
  },
  "links": [
    {
      "href": "https://api.bandwidth.com/v2/accounts/12345/whitelists",
      "rel": "self",
      "method": "PATCH"
    }
  ],
  "errors": []
}

Specific Sub-Account and Location Configurations

When you need to whitelist IP addresses for specific sub-accounts and locations, provide multiple whitelist entries with different subAccountId and locationId combinations. Each entry represents a separate service configuration.

Example Request

PATCH https://api.bandwidth.com/api/v2/accounts/12345/whitelists
Content-Type: application/json
Authorization: Bearer mySecretToken

{
  "operation": "ADD",
  "whitelists": [
    {
      "ipAddresses": [
        "127.127.127.127"
      ],
      "subAccountId": "10001",
      "locationId": "100001"
    },
    {
      "ipAddresses": [
        "128.128.128.128"
      ],
      "subAccountId": "20002",
      "locationId": "200002"
    }
  ]
}

Example Response

{
  "data": {
    "operation": "ADD",
    "whitelists": [
      {
        "ipAddresses": [
          "127.127.127.127",
          "127.127.127.128",
          "127.127.127.129"
        ],
        "subAccountId": "10001",
        "locationId": "100001"
      },
      {
        "ipAddresses": [
          "128.128.128.128",
          "128.128.128.129",
          "128.128.128.130"
        ],
        "subAccountId": "20002",
        "locationId": "200002"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.bandwidth.com/v2/accounts/12345/whitelists",
      "rel": "self",
      "method": "PATCH"
    }
  ],
  "errors": []
}

Account-Level Whitelisting

For account-level operations, provide a single whitelist entry with both subAccountId and locationId set to null. This can be used to whitelist exclusively for E911, if enabled on the account.

Example Request

PATCH https://api.bandwidth.com/api/v2/accounts/12345/whitelists
Content-Type: application/json
Authorization: Bearer mySecretToken

{
  "operation": "ADD",
  "whitelists": [
    {
      "ipAddresses": [
        "126.126.126.126"
      ]
    }
  ]
}

Example Response

{
  "data": {
    "operation": "ADD",
    "whitelists": [
      {
        "ipAddresses": [
          "126.126.126.126",
          "126.126.126.127",
          "126.126.126.128"
        ]
      }
    ]
  },
  "links": [
    {
      "href": "https://api.bandwidth.com/v2/accounts/12345/whitelists",
      "rel": "self",
      "method": "PATCH"
    }
  ],
  "errors": []
}

Request Parameters

The request uses a unified structure with a whitelists array:

Parameter	Type	Required	Description
operation	string	Yes	Must be set to 'ADD'
whitelists	array	Yes	Array of whitelist entries

Whitelist Entry Structure

Each entry in the whitelists array contains:

Parameter	Type	Required	Description
ipAddresses	array	Yes	List of IP addresses (up to 10 per entry)
subAccountId	string/null	Yes	Sub-account identifier for specific configurations, or null for account-level
locationId	string/null	Yes	Location identifier for specific configurations, or null for account-level

Response Format

GET Response Format

The GET response contains the current whitelist configuration:

Field	Type	Description
whitelists	array	Complete list of all current whitelist entries

PATCH Response Format

The PATCH response includes the complete list of whitelisted entries after the update operation:

Field	Type	Description
operation	string	The operation that was performed ('ADD')
whitelists	array	Complete list of all whitelist entries after the operation

Whitelist Entry Structure

Each whitelist entry in both GET and PATCH responses contains:

Field	Type	Description
ipAddresses	array	Complete list of IP addresses for this entry
subAccountId	string/null	Sub-account identifier (for specific configurations) or null (for account-level)
locationId	string/null	Location identifier (for specific configurations) or null (for account-level)

Authentication

The whitelist endpoint requires authentication via Basic or Bearer token authentication. Include proper authentication credentials in all requests:

Authorization: Basic <base64-encoded-credentials>

or

Authorization: Bearer <token>

Error Handling

The whitelist API returns specific error codes for different validation and processing scenarios:

Common Error Responses

Maximum IP Limit Exceeded

{
  "data": null,
  "links": [],
  "errors": [
    {
      "code": "VCS-0174",
      "type": "VALIDATION",
      "description": "Whitelist IPs cannot exceed the maximum limit of 10. Please provide a valid list of IPs."
    }
  ]
}

Missing Required Fields

{
  "data": null,
  "links": [],
  "errors": [
    {
      "code": "VCS-0176",
      "type": "VALIDATION",
      "description": "At least one whitelist entry must be provided."
    }
  ]
}

Account Not Found

{
  "data": null,
  "links": [],
  "errors": [
    {
      "code": "VCS-0187",
      "type": "RESOURCE_NOT_FOUND",
      "description": "AccountId=123456 does not exist or is locked."
    }
  ]
}

Whitelist Invalid Request

{
  "data": null,
  "links": [],
  "errors": [
    {
      "code": "VCS-0182",
      "type": "VALIDATION",
      "description": "The whitelist request is invalid. Please check the request and try again."
    }
  ]
}

Rate Limiting

The API implements rate limiting to ensure fair usage. If you exceed the rate limit, you'll receive a 429 response:

{
  "data": null,
  "links": [],
  "errors": [
    {
      "code": "VCS-0098",
      "type": "RATE_LIMITED",
      "description": "Your account has made too many requests to this endpoint. Wait until 2025-01-01T00:00:00Z."
    }
  ]
}

note

The whitelist PATCH operation is additive, meaning new IP addresses are merged with existing whitelisted addresses. The response will show the complete list of all whitelisted addresses on the given subAccountId(s) and locationId(s) after the operation.