Whitelists

Manage IP whitelists for sub-users and ISP batches. Whitelisting an IP lets requests from that source skip Proxy-Authorization — useful for keyless server-to-server setups.

Scoping

Whitelists are per resource:

• Sub-user whitelist — gateway products (residential, mobile). Whitelisting an IP authorizes it for that sub-user, on that product.
• ISP batch whitelist — authorizes a source IP for every IP in that batch.

A single source IP can be whitelisted in many places independently.

Endpoints

Method	Path	Purpose
GET	/whitelists?subuser={id}	List sub-user's whitelisted IPs
POST	/whitelists	Add an IP
DELETE	/whitelists/{id}	Remove an IP
GET	/isp/batches/{id}/whitelist	List batch's whitelist
POST	/isp/batches/{id}/whitelist	Add to batch
DELETE	/isp/batches/{id}/whitelist/{id}	Remove from batch

Add to a sub-user

curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "subuser": "sub_01HX2K3PQ4M5",
       "product": "residential",
       "ip":      "203.0.113.5",
       "label":   "prod-eu-west-1"
     }' \
     https://api.helodata.com/v1/whitelists

Response:

{
  "id":         "wl_01HX2K3PQ4M5",
  "subuser":    "sub_01HX2K3PQ4M5",
  "product":    "residential",
  "ip":         "203.0.113.5",
  "label":      "prod-eu-west-1",
  "active":     true,
  "created_at": "2026-05-28T10:00:00Z"
}

IP / CIDR format

Input	Accepted
Single IPv4 (203.0.113.5)	yes
IPv4 CIDR (203.0.113.0/24)	yes — max /24 per entry
IPv6	yes (full address or up to /64)
Hostname	no

List

curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/whitelists?subuser=sub_01HX2K3PQ4M5&product=residential"

Remove

curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/whitelists/wl_01HX2K3PQ4M5"

Effective within 60 seconds.

ISP batch whitelist

# List
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist"

# Add
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"ip":"203.0.113.5","label":"prod"}' \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist"

# Remove
curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist/wl_01HX..."

Limits

Scope	Max entries
Per sub-user (per product)	50
Per ISP batch	50

A /24 CIDR counts as one entry — the gateway expands it server-side.

Errors

Status	Code	Meaning
409	already_whitelisted	The IP/CIDR is already on this whitelist
422	invalid_cidr	CIDR larger than /24 (IPv4) or /64 (IPv6)
422	over_limit	More than 50 entries on this scope