Skip to content
ProxyRequest/ DOCS

Create a customer account

POST
/users
curl --request POST \
  --url https://api.proxyrequest.com/api/v1/users \
  --header 'Accept-Language: de' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "[email protected]", "username": "developer", "password": "Correct-Horse-Battery-Staple-42", "first_name": "Dana", "last_name": "Morgan", "country": "us", "state": "state", "city": "los_angeles", "address": "address", "zip": "zip", "blocked_domains": [ "blocked.example" ], "allowed_ips": [ "198.51.100.25" ], "connection_limit": 1, "is_reseller": false, "is_top_level": false, "data": 1073741824, "package_id": "550e8400-e29b-41d4-a716-446655440002", "meta": {} }'

Creates a sub-user under the caller by default. A superuser can send is_top_level=true to create an independent customer account. A sub-user cannot create another generation of users. Omit package_id and data to create identity only, then provision the chosen accounting model separately. For shared-pool allocation, supply package_id and positive integer-byte data; the parent must already own a root order for that package. An independent paid purchase is provisioned through invoices, not a shared-pool quota.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 255 characters

Stable key for one logical mutation. Successful responses are replayable for 24 hours; reusing a key with a different request returns 409.

Accept-Language
string
default: en

Preferred language for human-readable API errors. Supported languages: en, ru, uk, de, it, fr, es, zh-hans, ja. Regional language tags and quality weights are accepted; unsupported or omitted values use English.

Examples
de

Request Bodyrequired

Section titled “Request Bodyrequired”

Fields accepted when a reseller or administrator creates a customer account.

object
email

User’s email address. Must be unique if provided.

string format: email
username
required

Unique username for the account. Must be 4-128 characters.

string
>= 4 characters <= 128 characters
password
required

Account password. Must be 8-128 characters long.

string
>= 8 characters <= 128 characters
first_name

User’s first name.

string
<= 128 characters
last_name

User’s last name.

string
<= 128 characters
country

User’s country of residence.

string
<= 128 characters
state

User’s state or province.

string
<= 128 characters
city

User’s city.

string
<= 128 characters
address

User’s street address.

string
<= 128 characters
zip

User’s postal/ZIP code.

string
<= 128 characters
blocked_domains

List of domains to block for this user.

Array<string>
allowed_ips

List of source IP addresses allowed for this user. The maximum list size is configured per deployment.

Array<string>
connection_limit

Maximum number of concurrent connections allowed for the user.

integer
>= -1 <= 1000000
is_reseller

Whether the user should have reseller privileges. Only superusers can create resellers.

boolean
is_top_level

Superuser only: true creates an independent account with no parent. False (default) creates a sub-user under the caller.

boolean
data

Initial integer-byte data amount. With package_id, a normal sub-user receives a virtual quota from the caller’s existing root order; is_top_level=true provisions a separate paid purchase. Omit both data and package_id to create identity without package access.

integer
package_id

ProxyRequest package UUID to assign to the user. Headless integrations resolve it from their local product mapping.

string format: uuid
meta

Additional metadata for the user. Maximum 50 fields.

object
key
additional properties
Examples
Exampleexample

Example request

{
  "email": "[email protected]",
  "username": "developer",
  "password": "Correct-Horse-Battery-Staple-42",
  "first_name": "Dana",
  "last_name": "Morgan",
  "country": "us",
  "state": "state",
  "city": "los_angeles",
  "address": "address",
  "zip": "zip",
  "blocked_domains": [
    "blocked.example"
  ],
  "allowed_ips": [
    "198.51.100.25"
  ],
  "connection_limit": 1,
  "is_reseller": false,
  "is_top_level": false,
  "data": 1073741824,
  "package_id": "550e8400-e29b-41d4-a716-446655440002",
  "meta": {}
}

Responses

Section titled “Responses”

201

Section titled “201”

The resource or action result was created successfully.

Media typeapplication/json

Customer account with contact details, security settings, package data, referral information, and managed sub-users visible to the caller.

object
id
required
string format: uuid
username
required

Value must contain only letters, numbers, and underscores. It must not start or end with an underscore.

string
<= 150 characters
email
required
string format: email
<= 254 characters
is_reseller
Reseller

Reseller can create sub-users and manage their data.

boolean
is_marketer
Marketer

Marketer can manage marketing campaigns and view analytics.

boolean
is_superuser
Superuser status

Designates that this user has all permissions without explicitly assigning them.

boolean
date_joined
required
string format: date-time
date_joined_ts
required

Timestamp of when the user joined

integer
first_name
string
<= 150 characters
last_name
string
<= 150 characters
balance
integer
<= 2147483647
language
  • en - EN * de - DE * fr - FR * it - IT * ru - RU
string
Allowed values: en de fr it ru
country
string
<= 255 characters
state
string
<= 255 characters
city
string
<= 255 characters
address
string
<= 255 characters
zip
string
<= 255 characters
company_name
string
<= 255 characters
company_address
string
<= 255 characters
company_city
string
<= 255 characters
company_postal_code
string
<= 255 characters
company_country
string
<= 255 characters
company_vat_number
string
<= 255 characters
allowed_ips
required

List of IP addresses allowed for this user

Array<string>
blocked_domains
required

List of domains blocked for this user

Array<string>
connection_limit

The maximum number of concurrent connections allowed for this package.

integer
>= -1 <= 2147483647
parent_id
required

ID of the parent user (for sub-accounts)

string
sub_users
required

Number of sub-users managed by this reseller

integer
referrals
required

Number of users referred by this user

integer
referral_id
string
<= 255 characters
referral_code
required
string
referral_data_earned
required
integer
referral_data_pending
required
integer
referral_balance_pending
required
integer
referral_balance_earned
required
integer
currency
required

Currency information for the user’s transactions

object
key
additional properties
string
coupons
required

Available coupons for this user

Array<object>
object
key
additional properties
orders
required

The user’s package orders, including inactive orders. Each order contains its own data allowance, usage, ledgers, and proxy credentials. An empty list means the user has no orders.

Array<object>
object
id
string
<= 36 characters
is_auto_renewal
required
boolean
auto_renewal_percentage
Auto Renewal Threshold (%)

When this percentage of the data allowance has been consumed, the order is automatically renewed if the user has sufficient balance. Set to 0 to disable auto-renewal. 80 → renew when 80% of data is used

integer
<= 70
auto_renewal_data
Auto Renewal Data (GB)

Amount of data in GB to add when auto-renewal is triggered. Set to 0 to use the package default.

integer
<= 10000
package
required
object
key
additional properties
proxy_password

Password used by the customer to authenticate proxy connections. Auto-generated by default — change only if a custom value is needed. Must be between 4 and 64 characters.

string
<= 64 characters
proxy_password_reset
Password Last Changed

Timestamp of the last proxy password change. Read-only — updated automatically whenever the password is rotated.

string format: date-time
nullable
pools

Private proxy pools assigned to this order. Pools restrict which proxy IPs are available to this customer. Leave blank to use the full provider pool.

Array<string>
data
Data Allowance (bytes)

Total data allowance for this order in bytes. 1073741824 = 1 GiB 10737418240 = 10 GiB

integer format: int64
<= 1000000000000000
data_remaining
required

Integer bytes. Root order: sum of usable ledger balances, not data minus data_spent. Virtual child order: max(data - data_spent, 0), a personal quota that does not guarantee the parent still has usable data.

integer
data_spent
Data Spent (bytes)

Total bytes consumed from this order’s data allowance so far. Updated in real time as the customer uses the proxy.

integer format: int64
>= -9223372036854776000 <= 9223372036854776000
ledgers
required

Usable, non-expired ledger balances for a purchased root order; empty for a virtual child order using its parent’s pool. Not a complete history. Array position does not identify the active ledger or spending order.

Array<object>
object
key
additional properties
latest_data_top_up
Latest Top-up (bytes)

Amount of data added to this order in bytes during the most recent top-up.

integer format: int64
>= -9223372036854776000 <= 9223372036854776000
latest_data_top_up_date
Latest Top-up Date

Timestamp of the most recent data top-up, set when an invoice is fulfilled.

string format: date-time
nullable
data_updated
required
Last Used
string format: date-time
updated
required
string format: date-time
created
required
string format: date-time
Examples
ExampleCreatedUser

Created user

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "email": "[email protected]",
  "username": "developer",
  "first_name": "Dana",
  "last_name": "Morgan",
  "is_reseller": false,
  "orders": []
}

Headers

Section titled “Headers”
Idempotency-Replayed
string
Allowed values: true

True when the response was replayed from a prior request.

ETag
string

Strong entity tag for optimistic concurrency control.

400

Section titled “400”

The request is malformed or violates a business rule.

Media typeapplication/json

Validation and API error payload. Field names may be added dynamically; field errors are returned as arrays of human-readable messages.

object
detail
string
non_field_errors
Array<string>
key
additional properties
One of:
string
Examples
ExampleValidationError

Validation error

{
  "non_field_errors": [
    "The request could not be processed."
  ]
}

Headers

Section titled “Headers”
Content-Language
string

Language used for human-readable errors.

401

Section titled “401”

Authentication credentials are missing, expired, or invalid.

Media typeapplication/json

Validation and API error payload. Field names may be added dynamically; field errors are returned as arrays of human-readable messages.

object
detail
string
non_field_errors
Array<string>
key
additional properties
One of:
string
Examples
ExampleAuthenticationRequired

Authentication required

{
  "detail": "Authentication credentials were not provided."
}

Headers

Section titled “Headers”
Content-Language
string

Language used for human-readable errors.

403

Section titled “403”

The authenticated account cannot perform this operation.

Media typeapplication/json

Validation and API error payload. Field names may be added dynamically; field errors are returned as arrays of human-readable messages.

object
detail
string
non_field_errors
Array<string>
key
additional properties
One of:
string
Examples
ExamplePermissionDenied

Permission denied

{
  "detail": "You do not have permission to perform this action."
}

Headers

Section titled “Headers”
Content-Language
string

Language used for human-readable errors.

409

Section titled “409”

The idempotency key is in progress or was reused for a different request.

Media typeapplication/json

Validation and API error payload. Field names may be added dynamically; field errors are returned as arrays of human-readable messages.

object
detail
string
non_field_errors
Array<string>
key
additional properties
One of:
string
Examplegenerated
{
  "detail": "example",
  "non_field_errors": [
    "example"
  ]
}

Headers

Section titled “Headers”
Content-Language
string

Language used for human-readable errors.