The Ping Proxies API follows RESTful principles with consistent URL patterns, standard HTTP methods, and JSON-formatted requests and responses. This page explains the core structural components of the API.

​
Base URL

All API requests should be made to the following base URL: 
https://api.pingproxies.com/1.0/

​
URL Structure

The API URLs follow a consistent pattern: 
/[version]/[scope]/[resource]/[action]/[identifier]

​
Components

ComponentDescriptionExamples
versionAPI version1.0
scopeAccess levelpublic, private
resourceThe resource typeproxy, service, proxy_user
actionOperation to performretrieve, search, create, edit
identifierResource ID (when applicable){proxy_id}, {service_id}
All Public API therefore follow this URL format: 
https://api.pingproxies.com/1.0/public/user/[resource]/[action]/[identifier]

​
Example URLs

/1.0/public/user/proxy/search
/1.0/public/user/proxy/retrieve/{proxy_id}
/1.0/public/user/proxy_user/create
/1.0/public/user/service/edit/{service_id}

​
HTTP Methods

The API uses standard HTTP methods to perform different actions:
MethodDescriptionExample Usage
GETRetrieve dataFetch a proxy, list services, search resources
POSTCreate dataCreate a new proxy user, generate a checkout
PATCHUpdate dataEdit a proxy user, update service metadata
DELETERemove dataCancel a service, delete a proxy user
Inconsistent HTTP Method: The route POST /public/user/proxy/list_by_id violates the established HTTP method convention. According to the convention, retrieval operations should use the GET method, but this endpoint uses POST for a retrieval operation. This is an intentional deviation to support sending large lists of UUIDs in the request body, which wouldn’t be practical with query parameters in a GET request.

​
Method and URL Mapping

The HTTP method and URL structure work together to define the operation:
OperationHTTP MethodURL PatternExample
List/SearchGET/resource/searchGET /proxy/search
RetrieveGET/resource/retrieve/{id}GET /proxy/retrieve/123
CreatePOST/resource/createPOST /proxy_user/create
UpdatePATCH/resource/edit/{id}PATCH /proxy/edit/123
DeleteDELETE/resource/delete/{id} or /resource/cancel/{id}DELETE /proxy_user/delete/123

​
Request Format

​
Headers

All requests should include the following headers:
HeaderDescriptionRequired
X-API-Public-KeyYour public API keyYes
X-API-Private-KeyYour private API keyYes
Content-Typeapplication/json for requests with a bodyFor POST/PATCH

​
Request Body

For POST and PATCH requests, data should be sent as JSON in the request body: 
{
  "proxy_user_id": "example_user",
  "proxy_user_password": "secure_password",
  "proxy_user_metadata": {
    "department": "Marketing",
    "project": "Q2 Campaign"
  }
}

​
Query Parameters

For GET requests, parameters are passed in the URL query string: 
/proxy/search?country_id=us&proxy_type=datacenter&page=1&per_page=25
Common query parameters include:
ParameterDescriptionExample
pagePage number for paginationpage=2
per_pageItems per pageper_page=50
sort_byField to sort by with optional directionsort_by=creation_datetime_desc

​
Response Format

All API responses are JSON objects with a consistent structure: 
{
  "data": {
    // Resource data or array of resources
  },
  "message": "Operation successful message",
  "page": 1,           // Only in paginated responses
  "per_page": 25,      // Only in paginated responses
  "total_count": 157,  // Only in paginated responses
  "item_count": 25     // Only in paginated responses
}

​
Success Responses

Successful responses include:
  • HTTP status code in the 200 range
  • data field containing the requested resource(s)
  • message field with a success message
Example of a successful retrieve operation: 
{
  "data": {
    "proxy_id": "abc123",
    "proxy_ip_address": "192.168.1.1",
    "proxy_status": "active"
    // Additional fields...
  },
  "message": "Proxy successfully retrieved."
}
Example of a successful search operation: 
{
  "data": [
    {
      "proxy_id": "abc123",
      "proxy_ip_address": "192.168.1.1"
      // Additional fields...
    },
    {
      "proxy_id": "def456",
      "proxy_ip_address": "192.168.1.2"
      // Additional fields...
    }
  ],
  "message": "Proxy search successful.",
  "page": 1,
  "per_page": 25,
  "total_count": 157,
  "item_count": 25
}

​
Error Responses

Error responses include:
  • HTTP status code in the 400 or 500 range
  • error field with the error type
  • message field with a description of the error
  • api_request_id field for reference when contacting support
Example error response: 
{
  "error": "Bad Request",
  "message": "The proxy_user_id field is required.",
  "api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of a request:
CodeDescriptionCommon Scenarios
200OKSuccessful GET, PATCH operations
201CreatedSuccessful POST operation
400Bad RequestInvalid parameters or data
401UnauthorizedInvalid or missing authentication
403ForbiddenInsufficient permissions
404Not FoundResource doesn’t exist
409ConflictResource already exists
422Unprocessable EntityValid request but operation failed due to business logic
500Internal Server ErrorServer-side error

​
Data Types

The API uses standard JSON data types:
TypeJSON RepresentationExample
String"text""proxy_type": "datacenter"
Number123 or 123.45"proxy_http_port": 8080
Booleantrue or false"proxy_user_is_strict_security": true
Object{ "key": "value" }"proxy_user_metadata": { "department": "Marketing" }
Array[ value1, value2 ]"restricted_service_ids": ["123-456", "789-012"]
Nullnull"service_promotional_code": null
Datetime2023-09-15 00:00:00"service_creation_datetime": "2023-09-15 00:00:00"

​
Date and Time Format

All date and time values in the API use the format below: 
YYYY-MM-DDT hh:mm:ss
Example: "2023-09-15 14:30:00" When filtering by dates, you can use:
  • Format: 2023-09-15 14:30:00
  • Date only: 2023-09-15