Customer API

The customer API lets scripts and integrations do what the dashboard does: list your services, generate connection strings, read usage, manage trusted IPs, browse prices, and create and pay invoices.

Base URL: https://api.trueproxies.com
Every path starts with /v1/
OpenAPI 3.1 document: https://api.trueproxies.com/v1/openapi.json
Every operation, with parameters and response fields: API reference

Create an API key

In the dashboard, open API and create a key. Give it a name, choose only the scopes the script needs, and pick an expiry of 30, 90 or 365 days. You can have up to 10 active keys and revoke any of them immediately.

Send the key as a bearer token:

curl https://api.trueproxies.com/v1/me \
  -H "Authorization: Bearer tp_api_YOUR_KEY"

GET /v1/catalog is the only operation that needs no key. It lists offers, cities and payment providers.

Scopes

Scope	Allows
`services:read`	Account, services, usage, analytics and live metrics
`proxy:read`	Generate connection strings, read the proxy username and password, run an end-to-end check, list trusted IPs
`proxy:write`	Change the proxy password, add and remove trusted IPs
`billing:read`	Your current prices, invoices and invoice PDFs
`billing:write`	Create, pay and cancel invoices
`reseller:read`	Managed customers, wallet balance and wallet transactions
`reseller:write`	Create, edit, suspend, resume and close managed customers, and change their proxy settings on their behalf
`reseller:purchase`	Buy for a managed customer, pay with the wallet and fund the wallet. The only permission that can spend the wallet

A request with a missing scope returns 403.

Common tasks

List your services:

curl https://api.trueproxies.com/v1/services \
  -H "Authorization: Bearer tp_api_YOUR_KEY"

Generate connection strings for a service (proxy:read). Use only the targeting and session options listed in that service’s capabilities:

curl -X POST https://api.trueproxies.com/v1/services/SERVICE_ID/endpoints \
  -H "Authorization: Bearer tp_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "us", "count": 5, "format": "user:pass@host:port"}'

The response is {"lines": [...]}. Each line contains your proxy credentials, so treat the output as a secret.

Buy a plan (billing:write). Creating an invoice charges nothing; paying it returns a checkout link:

curl -X POST https://api.trueproxies.com/v1/invoices \
  -H "Authorization: Bearer tp_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0f7e-2b0e-4d4e-9d1a-4c1f3a9b2e10" \
  -d '{"offer_key": "OFFER_KEY"}'

curl -X POST https://api.trueproxies.com/v1/invoices/INVOICE_ID/pay \
  -H "Authorization: Bearer tp_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0d9e5b1a-7c3f-4a8e-b2d6-9f4e1c7a3b58" \
  -d '{"provider": "stripe"}'

Take offer_key from GET /v1/catalog or GET /v1/catalog/priced. The pay call returns checkout_url and expires_at; open the link to complete the payment. provider is stripe (card) or cryptomus (crypto). An unpaid invoice can be cancelled with POST /v1/invoices/{id}/cancel.

Retries and idempotency

Send an Idempotency-Key header on invoice creation, payment and wallet top-ups; API-key requests without one are refused with 400. Repeating the same request with the same key replays the first response, with Idempotency-Replayed: true, instead of buying or paying twice. Reusing a key for a different request returns 409, as does a repeat that arrives while the first is still running.

Never retry a payment automatically after an uncertain result. Read the invoice status first with GET /v1/invoices/{id}: open, paid or cancelled.

Rate limits

Each account gets 300 requests per minute, shared across all of its keys. Over the limit, the API returns 429 with a Retry-After header; wait that many seconds before the next request.

Responses and errors

Timestamps are ISO 8601.
Money is in cents, in USD.
Responses with account data carry Cache-Control: no-store and an X-Request-ID header. Include the request ID when you contact support.

Errors return JSON with a machine-readable code, a message, and optional details for the values your code needs to act on:

{
  "code": "INVOICE_NOT_PAYABLE",
  "message": "invoice is past due"
}

Code	Meaning
`BAD_REQUEST`	A parameter or body field is invalid
`UNAUTHENTICATED`	Missing, expired or revoked API key
`FORBIDDEN`	The key lacks the scope for this operation
`NOT_FOUND`	The resource does not exist in your account
`CONFLICT`	Idempotency conflict or insufficient wallet funds
`RATE_LIMITED`	Over 300 requests per minute; honor `Retry-After`
`OFFER_UNAVAILABLE`, `CITY_UNAVAILABLE`, `CAPACITY_UNAVAILABLE`	The offer or city cannot be bought right now
`INVOICE_NOT_PAYABLE`	The invoice is already paid or cancelled, is past due, or its service can no longer be renewed or topped up
`TRIAL_NOT_ELIGIBLE`, `EMAIL_UNVERIFIED`	The account cannot take this action yet
`SERVICE_UNAVAILABLE`, `PROVIDER_ERROR`, `PIPE_UNAVAILABLE`, `INTERNAL`	Temporary; retry later, using the same idempotency key for purchases

Resellers

Reseller keys can act for a managed customer by adding the customer_id query parameter or sending an X-Customer-Id header, in addition to the operation’s own scope. Reads need reseller:read. Proxy and service changes (trusted IPs, projects, password) need reseller:write. Creating and paying invoices needs reseller:purchase, and on-behalf payments must use "provider": "wallet". A managed customer’s invoice is issued to the reseller. See the reference for the managed customer and wallet operations, and the Reseller program guide for the wallet limits.