# Residential Proxies

Operations for residential proxies

## Purchase additional traffic (Residential)

`POST /user/api/orders/{id}/add-bandwidth`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Purchase additional traffic (Residential)",
  "parameters": [
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddBandwidthRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Order paid successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Account owner traffic

`GET /user/api/proxies/profile`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Account owner traffic",
  "description": "Returns the parent account's own total and remaining data for the given proxy type, aggregated across the parent's orders. Unlike the sub-user endpoints, this reflects the data of the account owner, not a sub-user.",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "integer",
                "description": "Total allocated data in bytes"
              },
              "data_remain": {
                "type": "integer",
                "description": "Remaining data in bytes"
              },
              "data_spent": {
                "type": "integer",
                "description": "Consumed data in bytes"
              },
              "proxy_password": {
                "type": "string",
                "description": "Parent account's proxy password"
              }
            },
            "required": [
              "success",
              "data",
              "data_remain",
              "data_spent",
              "proxy_password"
            ]
          }
        }
      }
    },
    "400": {
      "description": "User resident not set / invalid proxy type",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## Sub-user list

`GET /user/api/proxies/sub-users`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Sub-user list",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "offset",
      "required": false,
      "schema": {
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "count": {
                "type": "integer",
                "description": "Total sub-users before pagination"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    },
                    "data_remain": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent",
                    "data_remain"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Get sub-user by ID

`GET /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Get sub-user by ID",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Delete sub-user

`DELETE /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Delete sub-user",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user deleted successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Edit sub-user (name/package)

`PATCH /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Edit sub-user (name/package)",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EditSubUserPayload"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user edited successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Create sub-user

`POST /user/api/proxies/sub-user`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Create sub-user",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "data": {
              "type": "integer"
            }
          },
          "required": [
            "name",
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Add traffic to sub-user

`POST /user/api/proxies/sub-user/{user_id}/data/add`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Add traffic to sub-user",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "Amount in GB"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic added to sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Subtract traffic from sub-user

`POST /user/api/proxies/sub-user/{user_id}/data/subtract`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Subtract traffic from sub-user",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "Amount in GB"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic subtracted from sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Change sub-user password

`POST /user/api/proxies/sub-user/{user_id}/password`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Change sub-user password",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user password changed successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Country list

`GET /user/api/proxies/countries`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Country list",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCountriesResponse"
          }
        }
      }
    }
  }
}
```

## Region list

`GET /user/api/proxies/regions`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Region list",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO country code",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedRegionsResponse"
          }
        }
      }
    }
  }
}
```

## City list

`GET /user/api/proxies/cities`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "City list",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Proxy type (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO country code",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "Region or state code",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCitiesResponse"
          }
        }
      }
    }
  }
}
```

## List ISPs

`GET /user/api/proxies/isps`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "List ISPs",
  "description": "Internet providers available inside a city; the fourth targeting level after country, region and city. Unlike the other location endpoints this one needs the full chain: `country_code`, `region_code` AND `city_code` are all required, because upstream ISPs are bound to a city. Premium package only: the ISP catalogue is not maintained for the standart and unlimited packages, and any other `proxy_type` is rejected with 400. ISPs are listed for major cities only, so an empty `results` with `count: 0` is a normal answer for a smaller city.",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Must be `premium`; ISP targeting is premium-only",
      "schema": {
        "type": "string",
        "enum": [
          "premium"
        ]
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO country code",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "Region or state code",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "city_code",
      "required": true,
      "description": "City code from GET /user/api/proxies/cities",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedIspsResponse"
          }
        }
      }
    },
    "400": {
      "description": "proxy_type is not `premium`, user resident is not set, or the user has no active order for the package",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          },
          "examples": {
            "notPremium": {
              "value": {
                "success": false,
                "message": "ISP targeting is available for the premium package only"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```