IP Whitelist

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

Overview

The whitelist endpoints support both retrieving and adding IP addresses through separate voiceWhitelists and e911Whitelists structures. This allows you to:

• Retrieve Current Whitelists: Get all currently whitelisted IP addresses for specific trunks or all trunks
• Voice Services: Whitelist IP addresses for voice communications with proper sub-account and location identifiers
• E911 Emergency Services: Whitelist IP addresses for E911 emergency services

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 voice whitelist or E911 whitelist entry must be provided
• Voice Service Identifiers: Voice whitelist entries must include subAccountId and locationId (both as strings)
• E911 Whitelists: E911 whitelist entries contain only IP addresses for emergency services

Get Trunk IP Whitelist Addresses

API Operation

GET https://api.bandwidth.com/api/v2/accounts/{accountId}/trunks/{trunkName}/ipAddresses

Retrieve all IP addresses currently whitelisted for a specific trunk's voice services and E911 emergency services configuration. This operation returns the complete whitelist configuration for the specified trunk, including voice whitelists organized by service identifiers and E911 whitelists for emergency services.

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

Get All Trunks IP Whitelist Addresses

API Operation

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

Retrieve all IP addresses currently whitelisted for all trunks in an account's voice services and E911 emergency services configuration. This operation returns the complete whitelist configuration for all trunks.

Query Parameters

Parameter	Type	Description
capabilityNameFilter	string	Filter results by specific capability name
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

Get Specific Trunk Response

Example Request

GET https://api.bandwidth.com/api/v2/accounts/12345/trunks/trunk1/ipAddresses
Authorization: Bearer mySecretToken

Example Response

{
    "capabilityName": "DEFAULT",
    "voiceWhitelists": [
        {
            "ipAddresses": ["127.127.127.127", "127.127.127.128"],
            "subAccountId": "10001",
            "locationId": "100001"
        },
        {
            "ipAddresses": ["128.128.128.128", "128.128.128.129"],
            "subAccountId": "20002",
            "locationId": "200002"
        }
    ],
    "e911Whitelists": [
        {
            "ipAddresses": ["129.129.129.129", "130.130.130.130"]
        }
    ]
}

Get All Trunks Response

Example Request

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

Example Response

{
    "trunks": [
        {
            "trunkName": "trunk1",
            "capabilityName": "DEFAULT",
            "voiceWhitelists": [
                {
                    "ipAddresses": ["127.127.127.127", "127.127.127.128"],
                    "subAccountId": "10001",
                    "locationId": "100001"
                },
                {
                    "ipAddresses": ["128.128.128.128", "128.128.128.129"],
                    "subAccountId": "20002",
                    "locationId": "200002"
                }
            ],
            "e911Whitelists": [
                {
                    "ipAddresses": ["129.129.129.129", "130.130.130.130"]
                }
            ]
        },
        {
            "trunkName": "trunk2",
            "capabilityName": "DEFAULT2",
            "voiceWhitelists": [
                {
                    "ipAddresses": ["127.127.127.127", "127.127.127.128"],
                    "subAccountId": "10001",
                    "locationId": "100001"
                },
                {
                    "ipAddresses": ["128.128.128.128", "128.128.128.129"],
                    "subAccountId": "20002",
                    "locationId": "200002"
                }
            ],
            "e911Whitelists": [
                {
                    "ipAddresses": ["129.129.129.129", "130.130.130.130"]
                }
            ]
        }
    ]
}

Update Trunk IP Whitelist Addresses

API Operation

PATCH https://api.bandwidth.com/api/v2/accounts/{accountId}/trunks/{trunkName}/ipAddresses

The trunk whitelist operation merges the provided IP addresses with any existing whitelisted addresses for voice services and E911 emergency services on the specified trunk.

Voice and E911 Whitelists

Example Request

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

{
  "operation": "ADD",
  "voiceWhitelists": [
    {
      "ipAddresses": [
         "127.127.127.127",
         "127.127.127.128"
      ],
      "subAccountId": "10001",
      "locationId": "100001"
    },
    {
      "ipAddresses": [
         "127.127.128.127",
         "127.127.128.128"
      ],
      "subAccountId": "20001",
      "locationId": "200001"
    }
  ],
  "e911Whitelists": [
    {
      "ipAddresses": [
         "129.129.129.129",
         "130.130.130.130"
      ]
    }
  ]
}

Example Response

{
    "operation": "ADD",
    "voiceWhitelists": [
        {
            "ipAddresses": [
                "127.127.127.126",
                "127.127.127.127",
                "127.127.127.128"
            ],
            "subAccountId": "10001",
            "locationId": "100001"
        },
        {
            "ipAddresses": [
                "127.127.128.126",
                "127.127.128.127",
                "127.127.128.128"
            ],
            "subAccountId": "20001",
            "locationId": "200001"
        }
    ],
    "e911Whitelists": [
        {
            "ipAddresses": [
                "126.126.126.126",
                "126.126.126.127",
                "126.126.126.128",
                "129.129.129.129",
                "130.130.130.130"
            ]
        }
    ]
}

Voice Services Only

When you need to whitelist IP addresses only for voice services, provide only voiceWhitelists entries with subAccountId and locationId combinations.

Example Request

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

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

E911 Emergency Services Only

For E911 emergency services whitelisting, provide only e911Whitelists entries containing IP addresses.

Example Request

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

{
  "operation": "ADD",
  "e911Whitelists": [
    {
      "ipAddresses": [
        "129.129.129.129",
        "130.130.130.130"
      ]
    }
  ]
}

Request Parameters

The request uses separate structures for voice and E911 whitelists:

Parameter	Type	Required	Description
operation	string	Yes	Must be set to 'ADD'
voiceWhitelists	array	No	Array of voice whitelist entries
e911Whitelists	array	No	Array of E911 whitelist entries

Note: At least one of voiceWhitelists or e911Whitelists must be provided.

Voice Whitelist Entry Structure

Each entry in the voiceWhitelists array contains:

Parameter	Type	Required	Description
ipAddresses	array	Yes	List of IP addresses (up to 10 per entry)
subAccountId	string	Yes	Sub-account identifier for voice services
locationId	string	Yes	Location identifier for voice services

E911 Whitelist Entry Structure

Each entry in the e911Whitelists array contains:

Parameter	Type	Required	Description
ipAddresses	array	Yes	List of IP addresses for E911 emergency services (up to 10 per entry)

Response Format

GET Trunk Response Format

The GET trunk response contains the current whitelist configuration for a specific trunk:

Field	Type	Description
capabilityName	string	The capability name associated with the trunk
voiceWhitelists	array	Complete list of voice whitelist entries
e911Whitelists	array	Complete list of E911 whitelist entries

GET All Trunks Response Format

The GET all trunks response contains whitelist configurations for all trunks:

Field	Type	Description
trunks	array	Array of trunk entries with their whitelist configurations

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')
voiceWhitelists	array	Complete list of voice whitelist entries after the operation
e911Whitelists	array	Complete list of E911 whitelist entries after the operation

Voice Whitelist Entry Structure

Each voice whitelist entry in responses contains:

Field	Type	Description
ipAddresses	array	Complete list of IP addresses for voice services
subAccountId	string	Sub-account identifier for voice services
locationId	string	Location identifier for voice services

E911 Whitelist Entry Structure

Each E911 whitelist entry in responses contains:

Field	Type	Description
ipAddresses	array	Complete list of IP addresses for E911 emergency services

Authentication

The trunk whitelist endpoints require 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 trunk 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-0192",
            "type": "VALIDATION",
            "description": "Whitelist IPs cannot exceed the maximum limit of 10. Please provide a valid list of IPs."
        }
    ]
}

Account Not Found

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

Whitelist Invalid Request

{
    "data": null,
    "links": [],
    "errors": [
        {
            "code": "VCS-0203",
            "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 trunk 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 for voice services (with subAccountId and locationId) and E911 emergency services after the operation.