Proxies.com API

Official documentation for the Proxies.com API (v2)

Introduction

Create, view and modify your Proxies.com proxies via our API. Be sure to set your header "accept" to "application/json".

Create and view your API key at https://www.proxies.com/account/profile

Base URL

https://www.proxies.com/api/v2

Authentication

Bearer YOUR_API_KEY

All API requests must include your API key in the Authorization header.

Example Request

curl -X GET "https://www.proxies.com/api/v2/proxy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
GET

/proxy

Gets all proxies on the account according to the search parameters

Query Parameters

Parameter Type Description
active boolean If set to 1 it will only retrieve active proxies. If set to 0 it will only retrieve inactive proxies.
type number Set to 4 for IPv4 proxies. Set to 6 for IPv6.
dedicated boolean Set to 1 to search for dedicated proxies. Set to 0 for shared. Omit for both
name string Will match any proxy with this string in the proxy name
ip string Will match any proxy with this string in the proxy IP address
port number Will match any proxy with the provided port
batch string A batch reference ID
limit number Limits the number of returned proxies (default: 1000)
offset integer How many records to offset/skip by. Used for paginating.

Response Example (200 OK)

[
  {
    "reference": "abcdef1234",
    "type": 6,
    "dedicated": false,
    "proxy_address": "beef:beef::beef",
    "connection_address": "1.1.1.1",
    "proxy_port": 12345,
    "username": "someReallyGenericLogin",
    "password": "correctHorseBatteryStaple",
    "auth_ips": [
      "2.2.2.2",
      "3.3.3.3"
    ],
    "created_at": "2021-01-30 23:59:59",
    "expires_at": "2021-02-30 23:59:59",
    "domains": [
      "proxies.com",
      "example.com"
    ],
    "auto_renew": true,
    "cost": 3.5,
    "auto_rotate": true,
    "rotate_time": 120,
    "country": "US",
    "state": "NC"
  }
]
GET

/proxy/{reference}

Gets details about a specific proxy

Path Parameters

Parameter Type Description
reference string The proxy reference ID

Response Example (200 OK)

{
  "reference": "abcdef1234",
  "type": 6,
  "dedicated": false,
  "proxy_address": "beef:beef::beef",
  "connection_address": "1.1.1.1",
  "proxy_port": 12345,
  "username": "someReallyGenericLogin",
  "password": "correctHorseBatteryStaple",
  "auth_ips": [
    "2.2.2.2",
    "3.3.3.3"
  ],
  "created_at": "2021-01-30 23:59:59",
  "expires_at": "2021-02-30 23:59:59",
  "domains": [
    "proxies.com",
    "example.com"
  ],
  "auto_renew": true,
  "cost": 3.5,
  "auto_rotate": true,
  "rotate_time": 120,
  "country": "US",
  "state": "NC"
}
PATCH

/proxy/authentication

Updates the authentication requirements for all or specified proxies in account.
This request is not instant and can take several minutes for all proxies to be updated.
This request can result in some proxies failing to be updated and others successfully updated.

Authentication requirements vary based on the proxy type:

  • Non-dedicated IPv4 where you are limited to specific domains requires EITHER Username+password OR IPs.
  • Dedicated IPv4 where you can access any domain requires IPs and Username+password is optional.
  • IPv6 requires IPs and Username+password is optional.

You can replace, append or remove IPs. When the setting "append" is set to true it will add the given IPs to the existing list.
When the setting "remove" is set to true it will remove the given IPs from the existing list.
If both settings are set to false or not provided it will replace the entire list.

Request Body Parameters

Parameter Type Description Required (with)
username string New username No (Yes with "password")
password string New password No (Yes with "username")
ips string IP list that can replace/append/remove No
append boolean If set to true will append the "ips" to allowed IP list. No (Yes with "ips")
remove boolean If set to true will remove the provided "ips" from existing proxy allowed IP list No (Yes with "ips")
search["ipType"] string[ipv4 | ipv6] If set to either "ipv4" or "ipv6" will limit this auth update to either IPv4 or IPv6 proxies No
search["proxyType"] string[dedicated | shared] If set to either "dedicated" or "shared" will limit this auth update to either dedicated or shared proxies No
search["username"] string If set it will limit this auth update to proxies with the specified username No
search["password"] string If set it will limit this auth update to proxies with the specified password No

Request Body

{
  "username": "somebadusername",
  "password": "correctHorseBatteryStaple",
  "append": true,
  "remove": false,
  "ips": [
    "1.1.1.1",
    "2.2.2.2"
  ],
  "search": {
    "ipType": "ipv4",
    "proxyType": "dedicated",
    "username": "someReallyGenericLogin",
    "password": "correctHorseBatteryStaple"
  }
}

Response

Parameter Type Description
success array[string] List of proxy references that were successfully queued for updates
failed[]["message"] string Description of error
failed[]["error_id"] string A consistent error ID for the same type of error. Currently: IP_AUTH_REQ, AUTH_REQ, GEN_ERR
failed[]["count"] integer Number of proxies with this error
failed[]["references"] array[string] List of proxy references with this error

Response Example (200 OK)

{
    "success": [
        "reference1",
        "reference2"
    ],
    "failed": [
        {
            "message": "This proxy requires IP Authentication",
            "error_id": "IP_AUTH_REQ",
            "references": [
                "reference3",
                "reference4"
            ],
            "count": 2
        }
    ]
}

Response

Parameter Type Description
message string Description of error
reference string Currently unused
error_id string An error ID that will be consistent for the same error.
error_reference string Currently unused

Response Example (422 Unprocessable Eneity)

{
    "message": "The selected search.ip type is invalid.",
    "reference": "",
    "error_id": "VALIDATION_ERROR",
    "error_reference": null
}
PATCH

/proxy/{reference}/rotate

Rotates the proxy's IP address if it's IPv6

Path Parameters

Parameter Type Description
reference string The proxy reference ID

Response Example (200 OK)

{
  "proxy_address": "beef:beef::abcd"
}
PATCH

/proxy/{reference}/authentication

Updates the authentication requirements for a proxy

Authentication requirements vary based on the proxy type:

  • Non-dedicated IPv4 where you are limited to specific domains requires EITHER Username+password OR IPs.
  • Dedicated IPv4 where you can access any domain requires IPs and Username+password is optional.
  • IPv6 requires IPs and Username+password is optional.

You can replace, append or remove IPs. When the setting "append" is set to true it will add the given IPs to the existing list.
When the setting "remove" is set to true it will remove the given IPs from the existing list.
If both settings are set to false or not provided it will replace the entire list.

Path Parameters

Parameter Type Description
reference string The proxy reference ID

Request Body

{
  "username": "somebadusername",
  "password": "correctHorseBatteryStaple",
  "append": true,
  "remove": false,
  "ips": [
    "1.1.1.1",
    "2.2.2.2"
  ]
}

Response Example (200 OK)

{
  "success": true
}
GET

/account/funds

Gets the available funds for the account

Response Example (200 OK)

{
  "amount": 100
}
PATCH

/proxy/{reference}/name

Updates the name of a proxy

Path Parameters

Parameter Type Description
reference string The proxy reference ID

Request Body

{
  "name": "My New Proxy Name"
}

Response Example (200 OK)

{
  "success": true
}
PATCH

/proxy/{reference}/auto-renew

Updates the auto-renewal setting for a proxy

Path Parameters

Parameter Type Description
reference string The proxy reference ID

Request Body

{
  "auto_renew": true
}

Response Example (200 OK)

{
  "success": true
}

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests:

Code Description
200 - OK Request was successful
400 - Bad Request The request was invalid or cannot be served
401 - Unauthorized Authentication credentials are missing or invalid
403 - Forbidden The request is understood but has been refused or access is not allowed
404 - Not Found The requested resource could not be found
429 - Too Many Requests Rate limit has been exceeded
500 - Server Error An error occurred on the server

Error Response Format

{
  "error": true,
  "message": "A human-readable error message",
  "code": "ERROR_CODE"
}

API Endpoints