# API Extraction (Whitelist Mode)

In whitelist mode, you extract batches of `IP:port` proxies via an HTTP GET request and connect to them directly — no credentials. The whitelist itself can also be managed via API, so the entire workflow can be fully programmatic.

## Prerequisites

1. An active Residential Proxies plan.
2. Your server's exit IP added to the whitelist (via the dashboard's Whitelist page, or the whitelist management API below).

## Extraction endpoint

```
GET https://api.eproxies.net/gateway_api/extract_ip
```

| Parameter | Required | Values | Description |
| --- | --- | --- | --- |
| `count` | Yes | Number | Number of proxies per extraction |
| `country` | No | Country code / `Global` | Region, e.g. `US`; `Global` means any country |
| `protocol` | No | `http` / `socks5` | Proxy protocol |
| `format` | No | `txt` / `json` | Response format |
| `session` | No | `sticky` / `random` | IP type: `sticky` (reuses the same batch of IPs) / `random` |
| `separator` | No | `crlf` / `br` / `cr` / `lf` / `tab` | Line separator for txt format: `\r\n`, `</br>`, `\r`, `\n`, `\t` |
| `st` | No | Custom string | Custom separator (used instead of `separator`) |

Examples:

```bash
# Extract 10 US HTTP proxies, JSON format, sticky IPs
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Extract 5 SOCKS5 proxies from random countries, txt format, one per line
curl "https://api.eproxies.net/gateway_api/extract_ip?count=5&protocol=socks5&format=txt&separator=lf&session=random"
```

With `format=json`, the response is an array of objects, each with an `ipAddress` and a `portValue` field:

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

```python
import requests

resp = requests.get(
    "https://api.eproxies.net/gateway_api/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "sticky"},
    timeout=30,
)
proxy_list = resp.json()

# Connect to the extracted proxies directly, no credentials needed
first = proxy_list[0]
endpoint = f"{first['ipAddress']}:{first['portValue']}"
proxies = {"http": f"http://{endpoint}", "https": f"http://{endpoint}"}
print(requests.get("https://ipinfo.io", proxies=proxies, timeout=30).json())
```

The list of extractable countries (returns the `country` code, `name`, and `flag_url` flag icon):

```
GET https://api.eproxies.net/gateway_api/country-list
```

> Extraction requests must come from a whitelisted IP or they will be rejected. The dashboard's API Extraction page provides a visual link builder.

## Whitelist management API

Whitelist entries can be added, removed, and listed purely via API — useful for maintaining the whitelist automatically when your exit IP changes. All three endpoints authenticate with `userName` (your username) + `userKeyValue` (your user key, available in the dashboard):

```bash
# Add a whitelist IP
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Remove a whitelist IP
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# List current whitelist entries
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

Typical automation flow (for environments without a fixed exit IP):

```python
import requests

BASE = "https://api.eproxies.net/gateway_api"
AUTH = {"userName": "USERNAME", "userKeyValue": "USER_KEY"}

# 1. Get this machine's current exit IP
my_ip = requests.get("https://ipinfo.io/json", timeout=30).json()["ip"]

# 2. Add it to the whitelist
requests.get(f"{BASE}/add-ip", params={**AUTH, "ipAddress": my_ip}, timeout=30)

# 3. Extract proxies and use them
proxies = requests.get(
    f"{BASE}/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "random"},
    timeout=30,
).json()
print(proxies)
```

## Credential mode vs. extraction mode

| | Credential mode | API extraction (whitelist) |
| --- | --- | --- |
| Targeting granularity | Country/state/city/ASN | Country |
| Session control | Fine-grained via sid/ttl | `session=sticky/random` per batch |
| Applicability | Software must support proxy auth | Any proxy-capable software |
| Best for | Code integrations, fine-grained collection | Legacy tools, bulk distribution, auth-free environments |

## OpenAPI Specification

A machine-readable definition of every endpoint on this page is available at [openapi.json](https://www.eproxies.io/docs/openapi.json) — import it into Postman / Swagger UI, or load it from an AI agent.