---
title: "Create a per-list configuration on a proxy package"
method: POST
path: "/proxies/{id}/lists"
tags: ["Proxies"]
---

# Create a per-list configuration on a proxy package

`POST /proxies/{id}/lists`

## Request

- Base URL: `https://dashboard.voidmob.com/api/v1`
- URL: `https://dashboard.voidmob.com/api/v1/proxies/{id}/lists`
- Auth: HTTP bearer

Creates a new geo-targeted list under a package. Geo rules:
- `country` (single) **xor** `countries` (array of 2-30) is required.
- `region`, `city`, `isp`, `zip` are only valid with a single `country`.
Violations return `400 PROXY_GEO_CONFLICT`.

Max 100 lists per package by default (higher per-package limits
available on request). The returned `entries[]` and
`credentials.port` are resolved and persisted before the response is
returned.

Pass `network` to authenticate the list by source IP instead of
login/password. `credentials` is then `null` and `entries[]` carries a
bare `host:port`. The whitelist is create-time only and an address can be
whitelisted on one list at a time, so a clash returns
`409 PROXY_NETWORK_UNAVAILABLE` - retry with a different address.

## Path parameters

- `id` string, required: Opaque proxy package identifier.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateProxyListRequest: Exactly one of `country` or `countries` is required. `rotation_period_seconds`, `rotation_mode`, and `format` default when omitted.
  - `name` string, required
  - `country` string: ISO-3166-1 alpha-2 (either case accepted, echoed back as sent). Mutually exclusive with `countries`.
  - `countries` string[]: Multi-country list. Mutually exclusive with `country`; subfilters (region/city/isp/zip) are not allowed with `countries`.
  - `region` string
  - `city` string
  - `isp` string
  - `zip` string
  - `rotation_period_seconds` integer
  - `rotation_mode` 'instant' | 'delayed_5s' | 'no_rotation_on_fail'
  - `format` 'login_pass_host_port' | 'http_url' | 'socks5_url' | 'host_port_login_pass_colon' | 'login_pass_host_port_colon' | 'host_port_login_pass_comma' | 'login_pass_host_port_at': Saved credential-format preference for the dashboard's list export. API `entries` are always `login:pass@host:port`. Each value names the exported line: - `login_pass_host_port`: `login:pass@host:port` - `http_url`: `http://login:pass@host:port` - `socks5_url`: `socks5://login:pass@host:port` - `host_port_login_pass_colon`: `host:port:login:pass` - `login_pass_host_port_colon`: `login:pass:host:port` - `host_port_login_pass_comma`: `host,port,login,pass` - `login_pass_host_port_at`: `login@pass@host@port` Deprecated names are still accepted on input but never returned: `host_port_login_pass` (= `host_port_login_pass_comma`), `host_port` (= `login_pass_host_port_colon`), `login_pass_at_host_port` (= `host_port_login_pass_colon`), `json` (= `login_pass_host_port_at`).
  - `network` string: IP-whitelist authentication. Comma-separated IPv4 addresses and/or /24-/32 subnets (max 5 entries, no spaces). The list then authenticates by source IP and returns `credentials: null`. Set at creation only - it cannot be changed on an existing list. An address can be whitelisted on one list at a time; a clash returns 409 PROXY_NETWORK_UNAVAILABLE.

## Response `201`

List created.

- object
  - `success` true, required
  - `data` object, required
    - `list` ProxyList, required
      - `id` string, required: Identifier for a per-list configuration inside a proxy package.
      - `proxy_id` string, required: Opaque proxy package identifier.
      - `name` string, required
      - `country` string, nullable
      - `countries` string[], nullable
      - `region` string, nullable
      - `city` string, nullable
      - `isp` string, nullable
      - `zip` string, nullable
      - `rotation_period_seconds` integer, required
      - `rotation_mode` 'instant' | 'delayed_5s' | 'no_rotation_on_fail', required
      - `format` 'login_pass_host_port' | 'http_url' | 'socks5_url' | 'host_port_login_pass_colon' | 'login_pass_host_port_colon' | 'host_port_login_pass_comma' | 'login_pass_host_port_at', required: Saved credential-format preference for the dashboard's list export. API `entries` are always `login:pass@host:port`. Each value names the exported line: - `login_pass_host_port`: `login:pass@host:port` - `http_url`: `http://login:pass@host:port` - `socks5_url`: `socks5://login:pass@host:port` - `host_port_login_pass_colon`: `host:port:login:pass` - `login_pass_host_port_colon`: `login:pass:host:port` - `host_port_login_pass_comma`: `host,port,login,pass` - `login_pass_host_port_at`: `login@pass@host@port` Deprecated names are still accepted on input but never returned: `host_port_login_pass` (= `host_port_login_pass_comma`), `host_port` (= `login_pass_host_port_colon`), `login_pass_at_host_port` (= `host_port_login_pass_colon`), `json` (= `login_pass_host_port_at`).
      - `credentials` ProxyCredentials, required
        - `host` string, required
        - `port` integer, required
        - `protocol` 'http', required
        - `username` string, required
        - `password` string, required
      - `entries` string[], required: Ready-to-paste connection strings in `login:pass@host:port` form, regardless of the saved `format` (which applies to the dashboard's list export). For IP-whitelist lists these are bare `host:port` strings. For SOCKS5, use the same host, port and credentials with a `socks5://` scheme; SOCKS5 also relays UDP, for QUIC (HTTP/3) to the target.
      - `network` string, nullable, required: Comma-separated IPv4 addresses/subnets whitelisted for this list, or null for login/password lists. Set when the list is created; immutable afterwards - delete and recreate the list to change it.
      - `activation_note` string, required: Operational hint to surface to the end user.
      - `created_at` string, date-time, required

## Other responses

- `400`: 400 - Geo targeting is invalid - subfilters require a single country.
- `404`: 404 - Proxy not found.
- `409`: Conflict - PROXY_NOT_READY, PROXY_LIST_LIMIT_EXCEEDED, or PROXY_NETWORK_UNAVAILABLE (the requested IP whitelist overlaps an address already in use on another list).

---

[API](https://skmtc.dev/voidmob/apis/voidmob-public-api.md) · [All operations](https://skmtc.dev/voidmob/apis/voidmob-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voidmob/apis/voidmob-public-api/revisions/066023313ebe?raw)