Skip to main content
POST
cURL
Only users with Admin or Ops roles can perform this action.
This API can modify your account settings, damage your operations or incur charges.
Paste your API key to the authorization field. To get an API key, Create an account and learn how to generate an API key

ISP proxy zone examples

Creating an ISP zone requires specific parameter combinations. The fields below are not optional. Omitting them will silently create the wrong zone type or billing plan.
Setting zone.type to ISP alone will create a Datacenter zone, not an ISP zone. You must also set plan.pool_ip_type to static_res. Country codes must be lowercase (e.g. us, gb). Uppercase codes return a misleading “no IPs available” error.

Shared ISP (pay-per-GB)

Shared ISP (unlimited bandwidth)

Setting bandwidth: unlimited alone does not activate unlimited billing. You must also include unl_bw_tiers: std.

Dedicated ISP (unlimited bandwidth)

Residential proxy zone

New Residential zones require KYC approval. For Residential zones created after July 7, 2026, adding a zone is available only to KYC-verified companies. A request from an account that has not completed KYC is blocked and returns HTTP 403 with a compliance error. Residential zones created on or before July 7, 2026 are unaffected and continue to work as expected. Start at KYC verification and see the Residential network access policy.
Creating any Residential proxy type (shared rotating, IPv6 or dedicated) after July 7, 2026 requires KYC approval by the Bright Data compliance team. There is no automatic or no-KYC path for these new zones. Without KYC, create an ISP or Datacenter zone instead.

Dedicated Residential (gIP) zone

A dedicated Residential zone allocates a gIP (group of IPs) that is exclusive to a fixed list of target domains. Create one by setting vips_type: "domain" and including domain_whitelist.
Dedicated Residential gIPs are domain-restricted. You must set vips_type: "domain" and include domain_whitelist (a space-separated list of target domains). vip_country applies only to dedicated zones. For a shared zone, set the country with the -country username flag instead. Country codes must be lowercase (e.g. us, gb).
The following payload creates a dedicated Residential zone with one US gIP scoped to example.com. This payload was verified working on July 9, 2026.
The allocated gIP is exclusive to the domains listed in domain_whitelist. Requests to any other domain are routed through Bright Data’s shared Datacenter proxies.

Shared Residential country targeting

For shared Residential zones, country is not set with vip_country. Target countries at request level with the -country-<code> flag in the proxy username (for example -country-us), or set default countries in the control panel. See How to configure your Residential proxy.

Dedicated Residential gIP errors

An invalid dedicated Residential (gIP) payload returns one of the following errors.

Residential 403 compliance errors

For Residential zones created after July 7, 2026, an Add-a-Zone request from an account that is not eligible returns HTTP 403 with one of the following compliance errors. Zones created on or before July 7, 2026 are not affected. See the proxy errors catalog for the full catalog. Each error returns a structured JSON body so integrations can branch on the stable code value. A company-email account without KYC receives kyc_required:
A personal-email account receives business_account_required, which does not offer KYC because personal accounts are not eligible:
Both bodies include an alternatives array with the exact plan objects to create a no-KYC ISP or Web Unlocker API zone instead. To create the ISP zone, send POST /zone with that plan object in place of the Residential one.

Authorizations

Authorization
string
header
required

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

  1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
  2. Include the API Key in the Authorization header of your requests
  3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

Body

application/json
zone
object
required
Example:
plan
SERP API · object
required

Creates a SERP API zone for scraping search engine results.

Response

201

Zone added