# Set cloud phone proxy

Bind a proxy to one or more Cloud Phones.
- **Preconditions**: provide at least one of `ids` or `uniqueIds`. The phones must belong to your team; they do **not** need to be powered on. A supplied `proxyId` must exist, otherwise the call is rejected.
- **Effect**: when `proxyId` is omitted or `0`, an existing proxy with identical connection details is reused and **a new proxy record is created in your team if none matches**. The proxy check state is reset and the previous proxy is remembered.
- **Completion**: synchronous. **Phones that are powered on receive the new proxy immediately — no restart is needed**; powered-off phones pick it up on next start.
- **Retry**: rebinding an existing `proxyId` is idempotent, but repeating a call that carries raw connection details can create another proxy record each time deduplication misses.

Documented business errors: `33300`, `33303`, `33320`, `14023`. See [Error Codes](../Getting%20Started/error-codes.md) for what each code means. Any operation can additionally return the common codes.

Endpoint: POST /api/cloudphone/setProxy
Version: 2026-09-05

## Request fields (application/json):

  - `ids` (array)
    List of cloud phone environment IDs
    Example: ["1558968155668507"]

  - `uniqueIds` (array)
    List of display sequence IDs of cloud phone environments (used as reference mapping if envIds are not provided)
    Example: [1001]

  - `proxy` (object)

  - `proxy.proxyId` (string)
    Proxy Configuration ID (If this value is greater than 0, it means reusing an existing proxy configuration; if empty or <=0, it represents using the subsequent detailed parameters to create/update proxy details)
    Example: 10002

  - `proxy.proxyIp` (string, required)
    Proxy server IP address
    Example: 192.168.1.100

  - `proxy.proxyPort` (integer, required)
    Proxy server port
    Example: 8080

  - `proxy.proxyName` (string)
    Proxy configuration name/description
    Example: test_proxy_01

  - `proxy.proxyProvider` (integer, required)
    Proxy type 0:http, 1:https, 2:socks5
    Example: 2

  - `proxy.username` (string)
    Proxy authentication username
    Example: admin

  - `proxy.password` (string)
    Proxy authentication password
    Example: pwd123

  - `proxy.refreshUrl` (string)
    API URL to refresh dynamic proxy IP
    Example: http://api.proxy.com/refresh

  - `proxy.country` (string)
    Country code of the proxy location (e.g. CN, US)
    Example: US

  - `proxy.state` (string)
    State/Province of the proxy location
    Example: California

  - `proxy.city` (string)
    City of the proxy location
    Example: Los Angeles

## Response 200:

  - `200` (unknown)
    Success. `data` is always null for this operation; the outcome is carried by `code`.

## Response 200 fields (application/json):

  - `code` (integer)
    Response code: 0 = success, >0 = error

  - `data` (null)

  - `msg` (string | null)
    Message; populated if code > 0

  - `requestId` (string)
    Unique request identifier; include it when contacting support