> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/whitelists.md).

# 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

```bash
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:

```json
{
  "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

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

## Remove

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

Effective within 60 seconds.

## ISP batch whitelist

```bash
# 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        |