OpenAPI Doc

Authentication

App Key Authentication

POST parameters:

app_key: {your_app_key}

Or as query parameter:

?app_key={your_app_key}

The app_key authentication key can be viewed on the personal center homepage after logging in.

Please keep the key secure, as it has administrator privileges for your account.

Response Format

All API endpoints return a unified JSON format:

{
	"code": 200,
	"message": "Operation successful",
	"data": {}
}

code: Status code, 200 indicates success, other values indicate failure
message: Response message
data: Response data

Base URL:

https://api.proxy4free.com

Proxy Account Management

Proxy Account List

GET

/cgi/whitelist-account/list

Response Example

200 Response

{
	"code": {},
	"msg": "string",
	"data": {
		"list": [
			{
				"id": 0,
				"username": "string",
				"password": "string",
				"created_at": "string",
				"remark": "string",
				"product_type": {},
				"usage_flow": 0,
				"limit_flow": 102400,
				"status": 0
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	object	false	none	none
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	none
»»» id	integer	false	none	Account ID
»»» username	string	false	none	Proxy account username
»»» password	string	false	none	Proxy account password
»»» created_at	string	false	none	Creation time
»»» remark	string	false	none	Remark
»»» product_type	object	false	none	none
»»» usage_flow	integer	false	none	Used traffic, unit: KB
»»» limit_flow	integer	false	none	Custom traffic limit: unit GB, max 102400, 0 for unlimited
»»» status	integer	false	none	Enable status: 1 enabled, 0 disabled

Add Proxy Account

POST

/cgi/whitelist-account/add

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"accounts": "user01:pass,user02:pass,user03:pass",
	"remark": "",
	"product_type": {}
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» accounts	body	string	No	Account password, please fill in the format username:password. Account and password only support numbers and letters, no special symbols or spaces allowed. Colon separates account and password. Supports batch addition, separated by English comma (,).
» remark	body	string	No	Proxy account description
» product_type	body	object	No	none

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Delete Proxy Account

POST

/cgi/whitelist-account/delete

Please note that deletion cannot be undone, and used traffic data cannot be queried. Deletion has approximately 5 minutes waiting time, during which charges may still occur.

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"accounts": "user01,user02"
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» accounts	body	string	No	Proxy accounts, only supports numbers and letters. Supports batch operations, separated by English comma (,)

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Disable Proxy Account

POST

/cgi/whitelist-account/disable

Disabling has approximately 5 minutes waiting time, during which charges may still occur.

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"accounts": "user01,user02"
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» accounts	body	string	No	Proxy accounts, only supports numbers and letters. Supports batch operations, separated by English comma (,)

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Enable Proxy Account

POST

/cgi/whitelist-account/enable

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"accounts": "user01,user02"
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» accounts	body	string	No	Proxy accounts, only supports numbers and letters. Supports batch operations, separated by English comma (,)

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Change Proxy Account Password

POST

/cgi/whitelist-account/change-password

Please note that after modification, there is a 5-minute waiting time during which the old password may still work.

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"account": "user",
	"password": "pass"
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» account	body	string	No	Proxy account, only supports numbers and letters.
» password	body	string	No	New proxy account password, only supports numbers and letters.

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Change Proxy Account Remark

POST

/cgi/whitelist-account/change-remark

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"account": "user",
	"remark": ""
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» account	body	string	No	Proxy account, only supports numbers and letters.
» remark	body	string	No	New proxy account remark, within 32 Chinese characters or 64 English characters.

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Change Proxy Account Traffic Limit

POST

/cgi/whitelist-account/change-limit

Please note that traffic statistics may have a delay of up to 5 minutes, meaning actual traffic consumption may exceed this limit.

Body Request Parameters

{
	"app_key": "stringstringstringstringstringst",
	"account": "user",
	"limit": 0
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	No	none
» app_key	body	string	No	Authorization key
» account	body	string	No	Proxy account, only supports numbers and letters.
» limit	body	integer	No	Traffic limit, unit: GB, 0 for no limit

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": null
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	null	false	none	none

Traffic Log Query

Usage Traffic Summary by Day

GET

/cgi/user-usage-flow/total

Request Parameters

Name	Location	Type	Required	Description
app_key	query	string(password)	Yes	Authentication key
start_time	query	string(Y-m-d H:i:s)	No	Start time, can be accurate to seconds. Please note that log records have a delay of up to 5 minutes. Default is within 7 days.
end_time	query	string(Y-m-d H:i:s)	No	End time, can be accurate to seconds. Please note that log records have a delay of up to 5 minutes. Default is current time.
username	query	string	No	Sub-account name, default queries all accounts, can specify sub-account. Please note that if you have added sub-accounts with the same name, this query will return all usage records for accounts with the same name.
product_type	query	number	No	Package type

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": [
			{
				"day": "2022-08-01",
				"flow": 0
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	none
»»» day	string	false	none	Date
»»» flow	integer	false	none	Consumed traffic, unit: KB

Package Query

Purchased Package List

GET

/cgi/user-product/list

Request Parameters

Name	Location	Type	Required	Description
app_key	query	string(password)	Yes	Authentication key
trade_no	query	string	No	Order number, please enter complete order number. Fuzzy search not supported.
page	query	number	No	Page number, default: 1
size	query	number	No	Page size, default: 20
product_type	query	number	No	Package type

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": [
			{
				"id": 0,
				"created_at": "2022-05-13 12:14:15",
				"expired_at": "2022-05-13 12:14:15",
				"product_type": {},
				"trade_no": "2022051312134339861461465434",
				"order": {
					"created_at": "2022-05-13 12:13:43",
					"pay_at": "2022-05-13 12:13:43",
					"title": "入门级"
				}
			}
		],
		"page": 1,
		"page_size": 20,
		"total_count": 0,
		"total_page": 0
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	none
»»» id	integer	false	none	Package ID
»»» created_at	string	false	none	Package effective time
»»» expired_at	string	false	none	Package expiration time, traffic cannot be used after expiration.
»»» product_type	object	false	none	none
»»» trade_no	string	false	none	Order transaction number
»»» order	object	false	none	none
»»»» created_at	string	false	none	Order creation time
»»»» pay_at	string	false	none	Order payment time
»»»» title	string	false	none	Order description
»» page	integer	false	none	Current page
»» page_size	integer	false	none	Page size
»» total_count	integer	false	none	Total record count
»» total_page	integer	false	none	Total page count

IP Extraction

Extract IP

GET

/cgi/ip/v3

Request Parameters

Name	Location	Type	Required	Description
app_key	query	string(password)	Yes	Access key
cc	query	string	No	Country or region
state	query	string	No	Province or state
city	query	string	No	City
format	query	string	No	Output format
lb	query	string	No	Separator, only valid for text format
num	query	number	No	Extraction quantity
life	query	number	No	Keep cycle - minutes
ep	query	string	No	Proxy network

Enum Values

Property	Value
ep	us
ep	hk
ep	de

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": [
			[
				"150.109.114.72:1140",
				"150.109.114.72:1141",
				"150.109.114.72:1142",
				"150.109.114.72:1143",
				"150.109.114.72:1144",
				"150.109.114.72:1145",
				"150.109.114.72:1146",
				"150.109.114.72:1147",
				"150.109.114.72:1148",
				"150.109.114.72:1149"
			]
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[any]	false	none	none

City List

GET

/cgi/ip/dynamic-citys

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": [
			{
				"name_zh_cn": "美国",
				"name_en": "United States",
				"continent_code": "NA",
				"country_code": "US",
				"items": [
					{
						"city": null,
						"state": null,
						"continent_code": null,
						"country_code": null
					}
				]
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	List
»»» name_zh_cn	string	false	none	Country or region name
»»» name_en	string	false	none	Country or region name
»»» continent_code	string	false	none	Continent code
»»» country_code	string	false	none	Country or region code
»»» items	[object]	false	none	Province or state
»»»» city	string	false	none	City name
»»»» state	string	false	none	Province or state name code
»»»» continent_code	string	false	none	Continent code
»»»» country_code	string	false	none	Country or region code

City Search

GET

/cgi/ip/dynamic-citys/search

Request Parameters

Name	Location	Type	Required	Description
country_code	query	string	Yes	Country or region code
state	query	string	Yes	State or province code

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": ["string"]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[string]	false	none	List

State List

GET

/cgi/ip/dynamic-states

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": [
			{
				"name_zh_cn": "美国",
				"name_en": "United States",
				"continent_code": "NA",
				"country_code": "US",
				"items": [
					{
						"state": null,
						"continent_code": null,
						"country_code": null
					}
				]
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	List
»»» name_zh_cn	string	false	none	Country or region name
»»» name_en	string	false	none	Country or region name
»»» continent_code	string	false	none	Continent code
»»» country_code	string	false	none	Country or region code
»»» items	[object]	false	none	Province or state
»»»» state	string	false	none	Province or state name code
»»»» continent_code	string	false	none	Continent code
»»»» country_code	string	false	none	Country or region code

State/Province Search

GET

/cgi/ip/dynamic-states/search

Request Parameters

Name	Location	Type	Required	Description
country_code	query	string	Yes	Country or region code

Response Example

200 Response

{
	"code": 200,
	"msg": "string",
	"data": {
		"list": ["string"]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success, 3 app_key invalid, 156 account not verified
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[string]	false	none	List

Extract Purchased Static IP List

GET

/cgi/ip/get-static-ip

Request Parameters

Name	Location	Type	Required	Description
country_code	query	string	No	Country or region code
product_type	query	number	No	Product type, 25: Static residential IP, 14: Data center IP
trade_no	query	string	No	Filter IP by order number
page	query	number	No	Page number
size	query	number	No	Items per page
status	query	number	No	Status, 1: Valid, 2: Invalid, 3: Expiring soon, 4: Under maintenance

Enum Values

Property	Value
product_type	14
product_type	25
status	1
status	2
status	3
status	4

Response Example

200 Response

{}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	none	Inline

Get Available Static IP Count by Region

GET

/cgi/static-ip-region

Request Parameters

Name	Location	Type	Required	Description
isp	query	string	No	IP type

Detailed Description

isp: IP type

IP Type	Description
1	Residential static IP
0	Data center static IP

Response Example

200 Response

{
	"code": 200,
	"msg": "请求成功",
	"data": {
		"list": [
			{
				"code": "US",
				"number": 55
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Request successful	Inline

Return Data Structure

Status Code 200

Name	Type	Required	Constraint	Description
» code	integer	false	none	Status code, 200 success
» msg	string	false	none	Status message
» data	object	false	none	none
»» list	[object]	false	none	none
»»» code	string	false	none	Country or region code
»»» number	integer	false	none	Quantity

Order Management

Order List

GET

/cgi/order/list

Request Parameters

Name	Location	Type	Required	Description
page_no	query	integer	No	none
page_size	query	integer	No	none
trade_no	query	string	No	Order number
status	query	integer	No	Order status
product_type	query	integer	No	Product type

Detailed Description

status: Order status

Status	Description
0	Pending payment
1	Paid
2	Cancelled due to timeout
3	Refunded

product_type: Product type | Product Type | Description | |---|---| |3|Balance recharge| |9|Dynamic traffic package| |11|Dynamic global hourly package V2| |12|Long-term IDC traffic package| |13|Residential static IP traffic package| |14|Data center static IP package| |15|Long-term ISP traffic package| |16|Static traffic package| |17|Dynamic IP quantity package| |18|web-scraper| |19|Static IP renewal| |20|Static IP replacement quota| |21|Static traffic package v2| |24|Static traffic add-on package| |25|Residential static IP package| |26|Supplementary order - Some payment channels require users to manually fill in the amount, such as: cryptocurrency. If there is a shortage, contact customer service to make a supplementary payment through this product| |27|Serp| |28|Video|

Enum Values

Property	Value
status	0
status	1
status	2
status	3
product_type	3
product_type	9
product_type	11
product_type	12
product_type	14
product_type	16
product_type	17
product_type	18
product_type	19
product_type	21
product_type	24
product_type	25
product_type	26
product_type	27
product_type	28

Response Example

200 Response

{
	"data": {
		"list": [{}],
		"pagination": {}
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Success	Inline

Return Data Structure

Create Order

POST

/cgi/order/create

Due to the variety of package types and different configurations for each package, please fill in the parameters according to the actual situation. Improper parameter filling may cause order creation to fail.

examples:

Renew Static IP

{
    "pid": x, // Contact customer service to obtain
    "upids": "1,2,3,4,5,6", // Get corresponding IDs from /cgi/ip/get-static-ip
    "pm_id": 1 // Get from /cgi/payment/list
    "coupon_sn: "xxx", // Optional coupon
  }

Body Request Parameters

{
	"pid": 0,
	"upids": "string",
	"amount": 0,
	"pm_id": 0,
	"region_list": "string",
	"coupon_sn": "string",
	"use_invitation_registration_discount": true,
	"renew_duration": 0,
	"product_sku_bandwidth_id": 0,
	"product_sku_concurrency_id": 0,
	"recharge_amount": 0
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	Yes	none
» pid	body	integer	Yes	Package ID
» upids	body	string	No	Renewal package ID list
» amount	body	number	No	New purchase package quantity
» pm_id	body	integer	Yes	Payment method ID
» region_list	body	string	No	Specify region + quantity when purchasing static IP
» coupon_sn	body	string	No	Coupon number
» use_invitation_registration_discount	body	boolean	No	Whether to use invitation registration discount
» renew_duration	body	integer	No	Renewal duration - optional for static IP
» product_sku_bandwidth_id	body	integer	No	Package 11: Bandwidth package ID
» product_sku_concurrency_id	body	integer	No	Package 11: Concurrency package ID
» recharge_amount	body	integer	No	Package 3: Recharge amount

Response Example

200 Response

{
	"data": {}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Created successfully	Inline

Return Data Structure

Cancel Order

POST

/cgi/order/close

Body Request Parameters

{
	"trade_no": "string"
}

Request Parameters

Name	Location	Type	Required	Description
body	body	object	Yes	none
» trade_no	body	string	Yes	none

Response Example

200 Response

{}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Operation successful	Inline

/cgi/user/info

Response Example

200 Response

{
	"data": {}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Success	Inline

/cgi/payment/groups

Request Parameters

Name	Location	Type	Required	Description
trade_no	query	string	No	Order number - Can be passed when specific payment methods are needed for certain orders

Response Example

200 Response

{
	"data": {
		"list": [
			{
				"name": "string",
				"logos": [null],
				"items": [null]
			}
		]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	Retrieved successfully	Inline

/cgi/activity/balance-recharge-gift-ratio

Balance recharge gift ratio

Response Example

200 Response

{
	"data": {
		"list": [null]
	}
}

Return Result

Status Code	Status Code Meaning	Description	Data Model
200	OK	OK	Inline