ProxyZing.Com API Documentation

curl "https://api.proxyzing.com/api/v1/me/" \
  -H "X-API-Key: ...pxy"

Build the purchase body from the plan configuration

Every value you send comes from the plan configuration (plan detail). Add the _code suffix to every option name, except protocol, which keeps its name.

curl -X POST "https://api.proxyzing.com/api/v1/public/proxy-plans/proxy-dan-cu-viettel/purchase/" \
  -H "X-API-Key: ...pxy" \
  -H "Idempotency-Key: 7f3c9a2e-4b1d-4c8e-9a51-2d6f0b8e1c33" \
  -H "Content-Type: application/json" \
  -d '{"period_code":"daily","quantity":1,"selected_options":{"location_code":"17","protocol":"http"}}'

curl -X POST "https://api.proxyzing.com/api/v1/proxies/<proxy_id>/renew/" \
  -H "X-API-Key: ...pxy" \
  -H "Idempotency-Key: 0c5e8a1b-6d24-4f7a-8b39-91e2a4c7d5f0" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

Create an API key. Then send the key in the header of every request:

• The full key is shown only once when it is created. If you lose it, delete it and create a new one. You can revoke a key at any time and it stops working immediately.
• Never send the key in the query string. Do not use Authorization: Bearer for API keys.
• Use the key only on your own server, never in a web or mobile app.
• Every action (reading data, charging the balance) applies to the account the key belongs to.
• Store the key in an environment variable or a secrets manager, never in source code or a repository. If you suspect the key has leaked, revoke it immediately and create a new one.
• Account operations (creating or revoking keys, changing the password, depositing and withdrawing, editing the profile) are not available with an API key, only on the dashboard.
• Only accounts with the customer role can use API keys. Keys created by staff or admin accounts are rejected when calling the API (401).

Account

Plan

Order

Proxy

* For revoked proxies, the fields ip_address, http_port, socks5_port, country, username and password are all null. Handle null for this whole group.

Balance transaction

How to use it

1. Generate one unique key for each of your actions (UUID v4 recommended, up to 255 characters) and send it in the Idempotency-Key header.
2. If the request fails on the network or times out, resend exactly the same request with exactly the same key (same URL, same body).
3. To make a new purchase, use a new key.

Server responses

Notes

• Keys are scoped to each account and are valid for 24 hours. After 24 hours, reusing an old key is treated as a new request.
• A replayed result is rebuilt from current data, so for renewals the proxy returned is in its latest state.
• If you receive 409 several times in a row (a few minutes), the original request may have been interrupted midway. Check GET /proxy-orders/?ordering=-created_at or GET /proxies/{id}/ to see whether the order or expiry has been updated. Do not change the key and buy again before checking.
• If you do not send Idempotency-Key, the server does not de-duplicate and every request is a new purchase or renewal.

Generating and keeping the key

• The caller generates the key (the server does not issue one), for example crypto.randomUUID() in JavaScript or uuid.uuid4() in Python. The key must exist before the request is sent so it can be reused after a timeout.
• Generate it once each time the user starts a purchase or renewal (for example when the form or confirmation modal opens) and keep it. Do not create a new key on every button click or every call of the sending function, or duplicates are not prevented.
• Every resend of the same purchase (retry, double click) reuses the same key with an identical body.
• After a successful purchase or renewal, discard the key. The next purchase, even of the same plan, uses a new key. If a user deliberately buys twice, use two different keys and both are counted.

Handling responses on the client

For web apps that call the API from the server (for example a Next.js server action), the key must be generated on the UI side when the form opens and passed down to the server, which forwards it as the header. If the server action generates a new key every time it is called, it does not prevent duplicates.

import { randomUUID } from "node:crypto";

const API_BASE = "https://api.proxyzing.com/api/v1/";
const API_KEY = process.env.PROXYZING_API_KEY;

async function api(path, { method = "GET", body, idempotencyKey } = {}) {
  const headers = { "X-API-Key": API_KEY };

  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;

  const response = await fetch(API_BASE + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(90_000),
  });
  const data = await response.json();

  if (!response.ok) {
    throw Object.assign(new Error(data.error.message), {
      status: response.status,
      code: data.error.code,
      details: data.error.details,
    });
  }

  return data;
}

async function purchase(slug, body) {
  const idempotencyKey = randomUUID();

  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      return await api("public/proxy-plans/" + slug + "/purchase/", {
        method: "POST",
        body,
        idempotencyKey,
      });
    } catch (error) {
      const retryable =
        error.status === undefined || error.code === "request_in_progress";

      if (!retryable || attempt === 3) throw error;

      await new Promise((resolve) => setTimeout(resolve, 3000));
    }
  }
}

console.log(await api("me/"));
console.log(
  await purchase("proxy-dan-cu-viettel", {
    period_code: "daily",
    quantity: 1,
    selected_options: { location_code: "17", protocol: "http" },
  }),
);

import os
import time
import uuid

import requests

API_BASE = "https://api.proxyzing.com/api/v1/"
HEADERS = {"X-API-Key": os.environ["PROXYZING_API_KEY"]}


def get_me():
    response = requests.get(API_BASE + "me/", headers=HEADERS, timeout=30)
    response.raise_for_status()
    return response.json()


def purchase(slug, body):
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(1, 4):
        try:
            response = requests.post(
                API_BASE + "public/proxy-plans/" + slug + "/purchase/",
                json=body,
                headers=headers,
                timeout=90,
            )
        except requests.RequestException:
            if attempt == 3:
                raise
            time.sleep(3)
            continue

        if response.status_code == 409 and attempt < 3:
            time.sleep(3)
            continue

        response.raise_for_status()
        return response.json()


print(get_me())
print(
    purchase(
        "proxy-dan-cu-viettel",
        {
            "period_code": "daily",
            "quantity": 1,
            "selected_options": {"location_code": "17", "protocol": "http"},
        },
    )
)

const API_BASE = "https://api.proxyzing.com/api/v1/";
const API_KEY = process.env.PROXYZING_API_KEY;

let url = API_BASE + "proxy-orders/?page_size=100";

while (url) {
  const response = await fetch(url, { headers: { "X-API-Key": API_KEY } });
  const page = await response.json();

  for (const order of page.results) {
    console.log(order.id);
  }

  url = page.next;
}

import os

import requests

API_BASE = "https://api.proxyzing.com/api/v1/"
HEADERS = {"X-API-Key": os.environ["PROXYZING_API_KEY"]}

url = API_BASE + "proxy-orders/?page_size=100"

while url:
    page = requests.get(url, headers=HEADERS, timeout=30).json()

    for order in page["results"]:
        print(order["id"])

    url = page["next"]

What if I lose my API key?

The full key is shown only once when it is created and cannot be viewed again. Delete the old key and create a new one.

Can I use an API key in a web or mobile app?

No. Use the key only on your own server, never in a web or mobile app.

How is the purchase price calculated?

The server calculates the price, you do not send one. Total = unit_total × quantity (bandwidth-priced plans: price_per_gb × bandwidth_gb).

Am I charged if a purchase fails?

If the balance is insufficient or the data is invalid, you are not charged and no order is created. If order processing fails after you were charged, the system automatically refunds exactly the amount charged and the order becomes failed.

Should I retry a purchase request that timed out?

Yes, resend exactly the same request with the same Idempotency-Key. The server does not buy or charge again. If it still fails, check GET /proxy-orders/?ordering=-created_at before buying again.

Can an expired proxy be renewed?

No. A proxy whose expires_at is earlier than the current time cannot be renewed. The API returns a 400 error with details.expires_at and you are not charged.