Reseller API

API Key Format

API keys are prefixed with cp_ followed by 64 hexadecimal characters.

cp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET https://catproxies.com/api/v1/public/account \
  -H "Authorization: Bearer cp_your_api_key_here"

Complete ISP workflow

# 1. List ISP packages - note resellerPrice (per IP), minQty, maxQty, locations[]
GET /api/v1/public/store?proxyType=Isp

# 2. Buy 5 IPs in the US (countryId from locations[].id)
POST /api/v1/public/order
{ "packageId": "...", "ispData": { "quantity": 5, "countryId": 1 } }
# Charged: resellerPrice × 5

# 3. Get the proxy lines (host / ports / login / password per IP)
GET /api/v1/public/order/{orderId}/proxies

# 4. Check extend cost (resellerPrice × 5 for another 30 days)
GET /api/v1/public/order/{orderId}/extendOptions

# 5. Extend - packageId is optional for ISP
POST /api/v1/public/order/{orderId}/extend
{}
# Charged: resellerPrice × 5 again

Complete Dedicated ISP workflow

# 1. List Dedicated ISP packages - note resellerPrice (per IP). locations[] is
#    EMPTY (pool-based, no country). Any quantity 1-100 costs the same per IP.
GET /api/v1/public/store?proxyType=IspP

# 2. Buy 5 IPs - pass ONLY the quantity (no countryId, no authMethod).
POST /api/v1/public/order
{ "packageId": "...", "ispData": { "quantity": 5 } }
# Charged: resellerPrice × 5. Term: a fixed 30 days.

# 3. Get the proxy lines (host / port / login / password per IP).
#    Normally ready immediately; if you get HTTP 202 { pending: true }, retry
#    in a few seconds.
GET /api/v1/public/order/{orderId}/proxies

# 4. Check the renewal cost (resellerPrice × 5 for another 30 days).
GET /api/v1/public/order/{orderId}/extendOptions

# 5. Renew - packageId is resolved from the order, so send an empty body.
POST /api/v1/public/order/{orderId}/extend
{}
# Charged: resellerPrice × 5 again, +30 days.

Connecting

Each line from /order/:id/proxies is one dedicated proxy with its own login/password. The same port (port_http = port_socks) serves HTTP, SOCKS5 and UDP-over-SOCKS5. There is no gateway host and no username-appended targeting.

http://<login>:<password>@<host>:<port>    # HTTP / HTTPS
socks5://<login>:<password>@<host>:<port>  # SOCKS5 (UDP supported)

Connection ports

Use the host from GET /order/:id (proxyCredentials.hostip). Pick the port for the protocol and rotation you want.

Targeting - append to the username

Keep the password as-is and append flags to the username. -type-residential is required; the rest are optional.

Add -lifetime-<minutes>-session-<id> to hold the same exit IP (lifetime up to 1440 minutes = 24h); omit the sticky flags for a fresh IP on every request. Discover valid countries, cities and ASNs with GET /gresi-targeting-options?orderId=... (see the Targeting endpoints).

Example

# Credentials from GET /order/:id
#   username: mtpeqbcevnemewc201120   password: jonxybfeuu
#   host:     HOST  (proxyCredentials.hostip)

# Rotating IP in the US (new IP per request) - HTTP port 9000
curl -x HOST:9000 \
  -U "mtpeqbcevnemewc201120-type-residential-country-us:jonxybfeuu" \
  https://ipinfo.io

# Sticky IP in Los Angeles for 30 minutes - sticky HTTP port 10000
curl -x HOST:10000 \
  -U "mtpeqbcevnemewc201120-type-residential-country-us-state-california-city-losangeles-lifetime-30-session-ab12:jonxybfeuu" \
  https://ipinfo.io

Connection endpoints

GET /order/:id returns proxyCredentials.hostip / port (the Americas HTTP gateway IP by default) plus an endpoints object with the ip:port for every region and protocol. The host is always the IP from your order; pick the endpoint whose region matches your target country, on HTTP or SOCKS5, using the ports below.

Targeting - append to the password

Keep the username as-is and append flags to the password. The first flag joins the password with a - and every flag after it with a _. All flags are optional — a bare password returns a worldwide IP.

A sticky session id (exactly 8 lowercase letters/digits) maps to one exit IP, held on a best-effort basis for the lifetime you set (up to 168h). Omit the session for a fresh IP on every request; use a unique id per proxy line to get a batch of different sticky IPs.

Rotating the password

POST /order/:id/reset-password issues a brand-new password for the order (see the Endpoints section). Because targeting flags are appended to the password, a reset changes the base password only - rebuild your proxy strings with the new base password and re-append the same flags. The old password stops working immediately and the new one takes 1 to 2 minutes to activate.

Country, state & city lists

Country is an ISO-2 code (lowercase). Cities and US states are the plain name in lowercase with no spaces or separators (losangeles, newyork). The downloadable reference includes the full country, city and US-state name lists (the exact tokens our own dashboard uses) plus all ports and flag formats. Cities are grouped by country (cities), US states are in us_states, and US cities per state are in us_state_cities. A token can still return 503 if that place has no live IP at the moment - just broaden the targeting.

Tip: any city in the world can be requested, but because the residential pool is dynamic, very small cities may fall back to the wider region. Prefer larger cities. If a request returns no IP, broaden the targeting.

Example

# Credentials from GET /order/:id  (HOST = your order's hostip - a plain
# unbranded IP; per-region HTTP/SOCKS5 ports are in the endpoints object)
#   username: hftjvbtwgxxxceb205604
#   password: ngnstzylne
#   Americas HOST:6011   Europe HOST:6012   Asia HOST:6013

# Worldwide, rotating (bare password = a fresh IP on every request)
curl -x HOST:6011 -U "hftjvbtwgxxxceb205604:ngnstzylne" http://ip-api.com/json
# -> {"status":"success","country":"Brazil","city":"Itapetininga","isp":"Fernanda Cristina Ruiz Matiazzo - ME","query":"170.245.17.156"}

# UK, city London, with the Quality filter (use the Europe endpoint)
curl -x HOST:6012 \
  -U "hftjvbtwgxxxceb205604:ngnstzylne-country-gb_city-london_streaming-1" \
  http://ip-api.com/json
# -> {"status":"success","country":"United Kingdom","city":"Isleworth","isp":"Vodafone BB","query":"62.49.108.249"}

# A DIFFERENT sticky IP per line: give each line its own unique 8-char session
curl -x HOST:6011 -U "hftjvbtwgxxxceb205604:ngnstzylne-country-us_session-a1b2c3d4_lifetime-1h" http://ip-api.com/json
curl -x HOST:6011 -U "hftjvbtwgxxxceb205604:ngnstzylne-country-us_session-e5f6g7h8_lifetime-1h" http://ip-api.com/json

# SOCKS5 works too - just use the region's SOCKS5 port
curl -x socks5h://HOST:6014 -U "hftjvbtwgxxxceb205604:ngnstzylne-country-us" http://ip-api.com/json

Connection ports

Use the host from GET /order/:id (proxyCredentials.hostip - each plan has its own gateway). Pick the port for the protocol you want.

Targeting - append to the username

Keep the password as-is and append flags to the username. All flags are optional - a bare username returns a worldwide rotating IP.

Omit the -session-... flag for a fresh IP on every request. Add -session-<id>-ttl-<seconds> to hold the same exit IP for the given number of seconds; use a unique id per proxy line for a batch of different sticky IPs. State, city and ASN draw from a live pool whose coverage shifts over time - if a request returns no IP, that spot is momentarily empty, so broaden the targeting (drop the city, then the state). Country-only always works.

Example

# Credentials from GET /order/:id
#   username: PbSI5fsWPI   password: <your-password>
#   host:     HOST  (proxyCredentials.hostip)

# Rotating IP in the US (new IP per request) - HTTP port 8080
curl -x HOST:8080 \
  -U "PbSI5fsWPI-country-US:PASSWORD" \
  https://ipinfo.io

# Sticky IP in Los Angeles held for 30 minutes (1800s) - HTTP port 8080
curl -x HOST:8080 \
  -U "PbSI5fsWPI-country-US-state-ca-city-losangeles-session-482913-ttl-1800:PASSWORD" \
  https://ipinfo.io

# SOCKS5 works too - use port 1080
curl -x socks5h://HOST:1080 -U "PbSI5fsWPI-country-US:PASSWORD" https://ipinfo.io

Analytics - GET /order/:id/unlimited-metrics

Read-only. All params are optional; invalid timeframe / interval values fall back to the defaults silently (no error), so validate against the lists below. interval only affects the overview series.

Response shapes by view:

# view=overview  (default)
payload: {
  metrics: {
    speed:     { "<proxy-username>": { bits_per_second, formatted_speed }, ... },
    server:    { cpu_usage, ram_usage },      // percentages
    bandwidth: { used }                       // lifetime bytes
  },
  series: [ { timestamp, downloaded_gb, uploaded_gb, total_gb, requests, success_rate } ],
  timeframe, interval,
  available                                   // false = stats backend temporarily down
}

# view=activity   (paginated recent connections)
payload: {
  activity:  [ { timestamp, domain, outcome, protocol,
                 downloaded_bytes, uploaded_bytes, duration_ms, client_ip } ],
  pagination:{ total, per_page, current_page, last_page },
  available
}
# outcome is one of: SUCCESS | ERROR | DOMAIN_BLOCKED | UDP

# view=top-domains   (destinations ranked by request volume, top 50)
payload: {
  topDomains:[ { domain, requests, success_rate, total_bandwidth,
                 total_downloaded, total_uploaded, avg_duration_ms } ],
  summary,
  available
}

Live speed is reported per proxy sub-account (keyed by username) - sum bits_per_second across the accounts for the plan's current throughput. Byte and GB figures in the series are per bucket; totals are yours to sum.

Complete Datacenter workflow

# 1. List Datacenter packages - note ips (IP count), bandwidth (GB pool), days
GET /api/v1/public/store?proxyType=DatacenterP

# 2. Check live IP stock per country before allocating
GET /api/v1/public/datacenterp-countries

# 3. Buy - country_proxies must total EXACTLY the package IP count
POST /api/v1/public/order
{
  "packageId": "...",
  "datacenterPData": {
    "country_proxies": { "US": 60, "DE": 20, "GB": 20 },
    "high_concurrency": false,
    "high_priority": false,
    "whitelisted_ips": false
  }
}

# 4. Read the IP list back (ip_list is refreshed live on every call)
GET /api/v1/public/order/{orderId}

# 5. Optional - whitelist your server IP for credential-less access
PATCH /api/v1/public/order/{orderId}/whitelist
{ "ip": "203.0.113.42" }

What GET /order/:id returns for Datacenter

{
  "payload": {
    "order": {
      "id": "c5c7c6b5-e488-420c-b436-e90e86031751",
      "package_title": "Datacenter Proxies - 1 Month - 100 IPs - 250GB",
      "status": "CONFIRMED",
      "proxyCredentials": {
        "username": "dcuser482913",
        "password": "dcpass91827",
        "total_bandwidth": 250,
        "used_bandwidth": 12.4,
        "bandwidth_left": 237.6,
        "available_bandwidth": 237.6,
        "expired_at": "2026-08-04T10:00:00.000Z",
        "port_http": "1338",
        "port_socks5": "1339",
        "whitelist_ip": [],
        "ip_list": [
          {
            "iso2": "US",
            "name": "United States",
            "cities": [
              { "ips": ["203.0.113.24", "203.0.113.57", "..."] }
            ],
            "count_ips": 60
          },
          { "iso2": "DE", "name": "Germany", "cities": ["..."], "count_ips": 20 }
        ],
        "country_list": {
          "countries": { "US": 60, "DE": 20, "GB": 20 },
          "proxyNumber": 100
        }
      }
    }
  }
}

Using the proxies

# Every IP in ip_list is a dedicated proxy. Same credentials on all of them.
#   HTTP:   <ip>:1338:<username>:<password>
#   SOCKS5: <ip>:1339:<username>:<password>

# STATIC - that exact IP every time
curl -x 203.0.113.24:1338 -U "dcuser482913:dcpass91827" https://ipinfo.io

# ROTATING - a new IP on every request: append -ttl-0 to the USERNAME on any of
# your IPs. That IP then rotates within its own country.
curl -x 203.0.113.24:1338 -U "dcuser482913-ttl-0:dcpass91827" https://ipinfo.io

# After whitelisting your server IP, credentials are optional (static only):
curl -x 203.0.113.24:1338 https://ipinfo.io

Connection gateways

IPv6 is served through country gateways - the exit country is chosen by which gateway you connect to, and the same username:password works on all of them. Locations: Worldwide, United States, Germany, United Kingdom, Netherlands. Ports: 1338 HTTP/HTTPS, 1339 SOCKS5.

The gateway addresses are returned per order by GET /order/:id - unbranded plain IPs, safe to pass straight to your own customers:

GET /api/v1/public/order/{orderId}
{
  "proxyCredentials": {
    "username": "...",
    "password": "...",
    "hostip": "<worldwide gateway>",   // default gateway
    "port": "1338",
    "ports": { "http": "1338", "socks5": "1339" },
    "endpoints": {                     // one gateway IP per country
      "ww": "...", "us": "...", "de": "...", "gb": "...", "nl": "..."
    },
    "usage": { "bandwidth_left": 87.4, ... }  // null on unlimited plans
  }
}

Sessions - append to the username

Default is rotating: a new IPv6 address on every request, nothing to configure. For a sticky session (keep the same exit IP), append -session-<id>-ttl-<seconds> to the username (password unchanged). The session id must be a number between 0 and 999999; ttl is the hold time in seconds, up to 86400 (24h) - e.g. ttl-1800 = 30 min, ttl-3600 = 1 hour. Use different session ids to hold several sticky IPs in parallel.

# Credentials + gateway IPs from GET /order/:id (same login on all gateways)
#   username: ipv6user291   password: v6pass817
#   endpoints.us -> US_GATEWAY,  endpoints.de -> DE_GATEWAY, ...

# Rotating - fresh IPv6 address on every request (US gateway)
curl -x US_GATEWAY:1338 -U "ipv6user291:v6pass817" https://api6.ipify.org

# Sticky - hold the same IPv6 exit for 60 minutes (ttl is in SECONDS: 60 min = 3600)
curl -x DE_GATEWAY:1338 \
  -U "ipv6user291-session-483920-ttl-3600:v6pass817" \
  https://api6.ipify.org

# SOCKS5
curl --socks5 US_GATEWAY:1339 -U "ipv6user291:v6pass817" https://api6.ipify.org

Proxy response codes

Connecting

Use the host and port from GET /order/:id (proxyCredentials.hostip / port, HTTP port 5000). The same credentials work for every location; you choose the location by the username flags below.

For a sticky IP add -sid-<id>-ttl-<duration>, where duration is one of 1m 5m 10m 30m 60m 120m 180m 240m (hold up to 4h). Omit the sticky flags for a fresh IP each request. All of region, city, isp and the sticky flags are optional.

Discovering locations

The valid country / region / city / ISP codes come from the Mobile Targeting endpoints (/mobile-targeting-options/*). Those endpoints share a limit of 60 requests per 10 minutes - cache them (the lists rarely change), or download the full offline snapshot from the Targeting section for bulk setup. For a static starting point you can also reuse the city and US-state name lists in the Premium Residential targeting reference - the same place names apply, though the exact set valid for mobile comes from the endpoints above.

Example

# Credentials from GET /order/:id
#   username: mobileuser71   password: mob9182pass
#   host: HOST  port: 5000

# Rotating mobile IP in the US (new IP per request)
curl -x HOST:5000 \
  -U "mobileuser71-country-US:mob9182pass" \
  https://ipinfo.io

# Rotating IP on AT&T anywhere in the US
curl -x HOST:5000 \
  -U "mobileuser71-country-US-isp-at&t+wireless:mob9182pass" \
  https://ipinfo.io

# Sticky IP on AT&T in California for 30 minutes
curl -x HOST:5000 \
  -U "mobileuser71-country-US-region-california-isp-at&t+wireless-sid-ab12-ttl-30m:mob9182pass" \
  https://ipinfo.io