Sub-Users API

GET /v1/sub-users Requires Auth

List Sub-Users

Retrieve all sub-users associated with the authenticated account. Returns an array of sub-user objects including their proxy credentials, traffic usage, limits, and lifecycle status.

curl https://api.proxyhat.com/v1/sub-users \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.proxyhat.com/v1/sub-users",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

sub_users = response.json()["payload"]
for user in sub_users:
    print(f"{user[\"proxy_username\"]} — {user[\"lifecycle_status\"]}")

const response = await fetch("https://api.proxyhat.com/v1/sub-users", {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const { payload: subUsers } = await response.json();
subUsers.forEach(u => console.log(`${u.proxy_username} — ${u.lifecycle_status}`));

req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/sub-users", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 200

{
  "success": true,
  "payload": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "proxy_username": "user_abc123",
      "is_default_user": false,
      "is_traffic_limited": true,
      "used_traffic": 1073741824,
      "traffic_limit": 5368709120,
      "lifecycle_status": "Active",
      "name": "Main proxy",
      "notes": null,
      "sub_user_group_id": null,
      "created_at": "2026-01-20T10:00:00Z"
    }
  ],
  "meta": {},
  "errors": [],
  "description": ""
}

Response

GET /v1/sub-users/{sub_user} Requires Auth

Get Sub-User

Retrieve a single sub-user by their UUID. Returns the full sub-user object including proxy credentials, traffic usage, limits, and current lifecycle status.

Path Parameters

Name	Type	Required	Description
sub_user	string	Required	The UUID of the sub-user to retrieve.

curl https://api.proxyhat.com/v1/sub-users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

sub_user_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.proxyhat.com/v1/sub-users/{sub_user_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

sub_user = response.json()["payload"]
print(f"{sub_user[\"proxy_username\"]} — {sub_user[\"lifecycle_status\"]}")

const subUserId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`https://api.proxyhat.com/v1/sub-users/${subUserId}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const { payload: subUser } = await response.json();
console.log(`${subUser.proxy_username} — ${subUser.lifecycle_status}`);

subUserID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-users/%s", subUserID)

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 200

{
  "success": true,
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "proxy_username": "user_abc123",
    "is_default_user": false,
    "is_traffic_limited": true,
    "used_traffic": 1073741824,
    "traffic_limit": 5368709120,
    "lifecycle_status": "Active",
    "name": "Main proxy",
    "notes": null,
    "sub_user_group_id": null,
    "created_at": "2026-01-20T10:00:00Z"
  },
  "meta": {},
  "errors": [],
  "description": ""
}

sub_user (path)

Response

POST /v1/sub-users Requires Auth

Create Sub-User

Create a new proxy sub-user with the specified credentials and optional traffic limits. The sub-user will be provisioned and ready to use once the lifecycle status becomes Active.

Request Body

Name	Type	Required	Description
proxy_password	string	Required	The password for proxy authentication.
is_traffic_limited	boolean	Optional	Whether to enforce a traffic limit on this sub-user.
traffic_limit	string	Optional	The traffic limit as a human-readable string (e.g. "5GB", "500MB"). Only applies when is_traffic_limited is true.
name	string	Optional	A friendly display name for the sub-user.
notes	string	Optional	Free-form notes or description for this sub-user.
sub_user_group_id	string	Optional	UUID of the sub-user group to assign this sub-user to.

curl -X POST https://api.proxyhat.com/v1/sub-users \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "proxy_password": "securepass123",
    "is_traffic_limited": true,
    "traffic_limit": "5GB",
    "name": "My proxy user"
  }'

import requests

response = requests.post(
    "https://api.proxyhat.com/v1/sub-users",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "proxy_password": "securepass123",
        "is_traffic_limited": True,
        "traffic_limit": "5GB",
        "name": "My proxy user",
    },
)

sub_user = response.json()["payload"]
print(f"Created: {sub_user[\"proxy_username\"]}")

const response = await fetch("https://api.proxyhat.com/v1/sub-users", {
  method: "POST",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    proxy_password: "securepass123",
    is_traffic_limited: true,
    traffic_limit: "5GB",
    name: "My proxy user",
  }),
});

const { payload: subUser } = await response.json();
console.log(`Created: ${subUser.proxy_username}`);

payload := strings.NewReader(`{
  "proxy_password": "securepass123",
  "is_traffic_limited": true,
  "traffic_limit": "5GB",
  "name": "My proxy user"
}`)

req, _ := http.NewRequest("POST", "https://api.proxyhat.com/v1/sub-users", payload)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 201

{
  "success": true,
  "payload": {
    "uuid": "660f9500-f30c-52e5-b827-557766550000",
    "proxy_username": "user_def456",
    "is_default_user": false,
    "is_traffic_limited": true,
    "used_traffic": 0,
    "traffic_limit": 5368709120,
    "lifecycle_status": "Active",
    "name": "My proxy user",
    "notes": null,
    "sub_user_group_id": null,
    "created_at": "2026-01-25T14:30:00Z"
  },
  "meta": {},
  "errors": [],
  "description": ""
}

Request Body (JSON)

Response

PUT /v1/sub-users/{sub_user} Requires Auth

Update Sub-User

Update an existing sub-user's properties. You can change the proxy password, traffic limits, display name, notes, or group assignment. Only the fields you include in the request body will be updated.

Path Parameters

Name	Type	Required	Description
sub_user	string	Required	The UUID of the sub-user to update.

Request Body

Name	Type	Required	Description
proxy_password	string	Optional	A new password for proxy authentication.
is_traffic_limited	boolean	Optional	Whether to enforce a traffic limit on this sub-user.
traffic_limit	string	Optional	The traffic limit as a human-readable string (e.g. "10GB", "500MB").
name	string	Optional	A friendly display name for the sub-user.
notes	string	Optional	Free-form notes or description for this sub-user.
sub_user_group_id	string	Optional	UUID of the sub-user group to assign this sub-user to. Pass null to remove from a group.

curl -X PUT https://api.proxyhat.com/v1/sub-users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Updated proxy user",
    "traffic_limit": "10GB"
  }'

import requests

sub_user_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.put(
    f"https://api.proxyhat.com/v1/sub-users/{sub_user_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "name": "Updated proxy user",
        "traffic_limit": "10GB",
    },
)

sub_user = response.json()["payload"]
print(f"Updated: {sub_user[\"name\"]}")

const subUserId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`https://api.proxyhat.com/v1/sub-users/${subUserId}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    name: "Updated proxy user",
    traffic_limit: "10GB",
  }),
});

const { payload: subUser } = await response.json();
console.log(`Updated: ${subUser.name}`);

subUserID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-users/%s", subUserID)

payload := strings.NewReader(`{
  "name": "Updated proxy user",
  "traffic_limit": "10GB"
}`)

req, _ := http.NewRequest("PUT", url, payload)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 200

{
  "success": true,
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "proxy_username": "user_abc123",
    "is_default_user": false,
    "is_traffic_limited": true,
    "used_traffic": 1073741824,
    "traffic_limit": 10737418240,
    "lifecycle_status": "Active",
    "name": "Updated proxy user",
    "notes": null,
    "sub_user_group_id": null,
    "created_at": "2026-01-20T10:00:00Z"
  },
  "meta": {},
  "errors": [],
  "description": ""
}

sub_user (path)

Request Body (JSON)

Response

DELETE /v1/sub-users/{sub_user} Requires Auth

Delete Sub-User

Delete a single sub-user by their UUID. The sub-user will be marked for deletion and their proxy credentials will be deactivated. The deletion is processed asynchronously.

Path Parameters

Name	Type	Required	Description
sub_user	string	Required	The UUID of the sub-user to delete.

curl -X DELETE https://api.proxyhat.com/v1/sub-users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

sub_user_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.delete(
    f"https://api.proxyhat.com/v1/sub-users/{sub_user_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

result = response.json()["payload"]
print(f"Status: {result[\"status\"]}")

const subUserId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`https://api.proxyhat.com/v1/sub-users/${subUserId}`, {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const { payload } = await response.json();
console.log(`Status: ${payload.status}`);

subUserID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-users/%s", subUserID)

req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 200

{
  "success": true,
  "payload": {
    "deleted": true,
    "status": "deleting"
  }
}

sub_user (path)

Response

POST /v1/sub-users/bulk-delete Requires Auth

Bulk Delete Sub-Users

Delete multiple sub-users in a single request. Provide an array of UUIDs to delete. The response includes a breakdown of how many were successfully deleted, skipped, not found, or failed.

Request Body

Name	Type	Required	Description
ids	array of strings	Required	An array of sub-user UUIDs to delete.

curl -X POST https://api.proxyhat.com/v1/sub-users/bulk-delete \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9500-f30c-52e5-b827-557766550000"
    ]
  }'

import requests

response = requests.post(
    "https://api.proxyhat.com/v1/sub-users/bulk-delete",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "ids": [
            "550e8400-e29b-41d4-a716-446655440000",
            "660f9500-f30c-52e5-b827-557766550000",
        ],
    },
)

result = response.json()["payload"]
print(f"Deleted: {result[\"deleted\"]}, Skipped: {result[\"skipped\"]}")

const response = await fetch("https://api.proxyhat.com/v1/sub-users/bulk-delete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    ids: [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9500-f30c-52e5-b827-557766550000",
    ],
  }),
});

const { payload } = await response.json();
console.log(`Deleted: ${payload.deleted}, Skipped: ${payload.skipped}`);

payload := strings.NewReader(`{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660f9500-f30c-52e5-b827-557766550000"
  ]
}`)

req, _ := http.NewRequest("POST", "https://api.proxyhat.com/v1/sub-users/bulk-delete", payload)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Response 200

{
  "success": true,
  "payload": {
    "requested": 3,
    "deleted": 2,
    "skipped": 1,
    "not_found": 0,
    "failed": 0
  }
}

Request Body (JSON)

Response

Listing & Retrieval

List Sub-Users

Get Sub-User

Creating & Updating

Create Sub-User

Update Sub-User

Deleting

Delete Sub-User

Bulk Delete Sub-Users