DF-IP User API: Getting Started
Set up authentication, understand scopes, and choose the right integration flow for dynamic and static proxies.
Use the DF-IP user API to look up dynamic proxy locations, generate proxy connection details, and query or purchase static residential proxies.
1. Get your API Key and API address
Sign in to the DF-IP web console and copy your API Key from your account page. Open API Interface to find the public API address configured for your account. Replace https://YOUR_API_HOST in these examples with that address. The help center domain is not necessarily the business API domain.
Call the API over HTTPS from your server. Keep your key in an environment variable or secret manager, and exclude it from public pages, source repositories, and logs. Treat returned proxy credentials as secrets too.
2. Choose the correct authentication format
| Function | Method and path | Credential location |
|---|---|---|
| Dynamic location lookup | GET /api/user_get_location_list | Api-Token header |
| Dynamic proxy generation | GET or POST /api/user_get_ip_list | token query parameter or form field |
| Account balance | GET /api/user/v1/account/balance | Api-Token header |
| Static inventory and business names | Read endpoints under /api/user/v1/static-residential/ | Api-Token header |
| Static quotes and purchases | quotes and orders under the same prefix | Api-Token; purchasing also requires Idempotency-Key |
| Static operations, orders, and purchased IPs | Read endpoints under the same prefix | Api-Token header |
The dynamic generation endpoint currently reads the key from token, not from the Api-Token header. Prefer a POST form to keep the key out of URLs, browser history, and URL access logs. Ensure your application does not log request bodies containing credentials. A help center publishing token or web session token is not a business API Key.
3. Make a read-only request
These examples use Bash and curl. Supply DFIP_API_KEY through your secret management process, then set the public API address. Avoid entering a real key into shell history.
export DFIP_API_BASE='https://YOUR_API_HOST'
curl --silent --show-error --max-time 30 \
"$DFIP_API_BASE/api/user/v1/account/balance" \
-H "Api-Token: $DFIP_API_KEY"
Check both the HTTP status and the JSON code. A business result with code: 0 is successful; the payload is in data, with a message in msg. Dynamic endpoints may return HTTP 200 for business errors, so HTTP status alone is insufficient.
{"code":0,"msg":"success","data":{}}
This shows the envelope only. Actual data fields depend on the endpoint. All hostnames, credentials, operation identifiers, and sample values in this documentation are illustrative, not live inventory, prices, or orders.
4. Static residential scopes
| Scope | Access |
|---|---|
account:read | Balance and current scopes |
static:inventory:read | Countries, cities, inventory, business names, and quotes |
static:ip:read | Your static residential orders and currently owned IP records |
static:purchase | Submit purchases and read purchase operations |
Purchase access must be granted explicitly. Some legacy keys retain read access, but that does not imply permission to buy. Check the scopes returned by the balance endpoint. A static API key with an IP allowlist must be used from an allowed outbound address. Subaccounts also need static residential access.
For a subaccount sharing its parent's balance, balance_source can be parent. Order ownership and IP visibility are still restricted to the calling account. Use static_purchase_available_balance for the purchasing budget; do not add gift or commission balances to it yourself.
5. Integration flows
- Dynamic proxies: look up locations, retain their
valuefields, and generate connection strings. Configure the returned host, port, username, and password in your proxy client. - Static residential proxies: read inventory and business names, request a quote, review its amount, submit a purchase with a unique idempotency key, poll the operation, and retrieve the IPs after
completed.
A purchase request can result in a real balance debit. Do not test retries by generating new idempotency keys. HTTP 202 means the operation was accepted, not that the proxies have been delivered.
Static list endpoints accept page and page_size, defaulting to 1 and 20, with at most 100 items per page. Dynamic location results use count and list instead of these pagination fields.
6. Handle errors and retries
- Authentication failures: check key validity, status, expiry, and where the key was sent.
- HTTP 403: check scopes, the IP allowlist, account status, and subaccount permissions.
- HTTP 400: correct the input before retrying.
- HTTP 429: reduce the request rate and honor
Retry-Afterwhen present. Limits depend on the deployed service. - Network timeouts and server errors: retry reads with backoff. For purchases, retain the original idempotency key and check the original operation.
Dynamic endpoints accept Accept-Language: zh-CN, zh-HK, or en for messages. Some static V1 error messages are currently fixed in Chinese. Branch on code, not the language or exact wording of msg.