# 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[​](#overview "Direct link to 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[​](#validation-rules "Direct link to 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[​](#get-trunk-ip-whitelist-addresses "Direct link to Get Trunk IP Whitelist Addresses") ### API Operation[​](#api-operation "Direct link to API Operation") ``` GET https://api.bandwidth.com/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[​](#query-parameters "Direct link to 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[​](#get-all-trunks-ip-whitelist-addresses "Direct link to Get All Trunks IP Whitelist Addresses") ### API Operation[​](#api-operation-1 "Direct link to API Operation") ``` GET https://api.bandwidth.com/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[​](#query-parameters-1 "Direct link to 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[​](#get-specific-trunk-response "Direct link to Get Specific Trunk Response") #### Example Request[​](#example-request "Direct link to Example Request") ``` GET https://api.bandwidth.com/v2/accounts/12345/trunks/trunk1/ipAddresses Authorization: Bearer mySecretToken ``` #### Example Response[​](#example-response "Direct link to 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[​](#get-all-trunks-response "Direct link to Get All Trunks Response") #### Example Request[​](#example-request-1 "Direct link to Example Request") ``` GET https://api.bandwidth.com/v2/accounts/12345/trunks Authorization: Bearer mySecretToken ``` #### Example Response[​](#example-response-1 "Direct link to 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[​](#update-trunk-ip-whitelist-addresses "Direct link to Update Trunk IP Whitelist Addresses") ### API Operation[​](#api-operation-2 "Direct link to API Operation") ``` PATCH https://api.bandwidth.com/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[​](#voice-and-e911-whitelists "Direct link to Voice and E911 Whitelists") #### Example Request[​](#example-request-2 "Direct link to Example Request") ``` PATCH https://api.bandwidth.com/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[​](#example-response-2 "Direct link to 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[​](#voice-services-only "Direct link to 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[​](#example-request-3 "Direct link to Example Request") ``` PATCH https://api.bandwidth.com/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[​](#e911-emergency-services-only "Direct link to E911 Emergency Services Only") For E911 emergency services whitelisting, provide only `e911Whitelists` entries containing IP addresses. #### Example Request[​](#example-request-4 "Direct link to Example Request") ``` PATCH https://api.bandwidth.com/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[​](#request-parameters "Direct link to 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[​](#voice-whitelist-entry-structure "Direct link to 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[​](#e911-whitelist-entry-structure "Direct link to 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[​](#response-format "Direct link to Response Format") ### GET Trunk Response Format[​](#get-trunk-response-format "Direct link to 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[​](#get-all-trunks-response-format "Direct link to 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[​](#patch-response-format "Direct link to 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[​](#voice-whitelist-entry-structure-1 "Direct link to 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[​](#e911-whitelist-entry-structure-1 "Direct link to 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[​](#authentication "Direct link to Authentication") The trunk whitelist endpoints require OAuth 2.0 bearer token authentication — see [Credentials & Authentication](/docs/account/credentials/management.md) to obtain a token: ``` Authorization: Bearer {YOUR_ACCESS_TOKEN} ``` ## Error Handling[​](#error-handling "Direct link to Error Handling") The trunk whitelist API returns specific error codes for different validation and processing scenarios: ### Common Error Responses[​](#common-error-responses "Direct link to Common Error Responses") #### Maximum IP Limit Exceeded[​](#maximum-ip-limit-exceeded "Direct link to 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[​](#account-not-found "Direct link to 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[​](#whitelist-invalid-request "Direct link to 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[​](#rate-limiting "Direct link to 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.