Skip to main content
POST
JavaScript
Provide exactly one proxy definition: the socks5 object, the deprecated flat host/port/user/password fields (all four required together), or a Mobilerun Connect connect reference (see below). Sending more than one fails validation.

Mobilerun Connect proxies

Instead of passing credentials, reference a Mobilerun Connect proxy:
fetches the credentials of an existing Connect proxy owned by the device’s owner (it must be active or cancelling), while
provisions a rotating residential proxy in that country — or reuses the one previously provisioned for this device when it is still active and in the same country. Provisioning waits up to 60 s for the proxy to become active. If payment is required first, the request fails with 402 PAYMENT_REQUIRED and a paymentUrl detail pointing to checkout. With smartIp: true, the exit-IP precheck probes the proxy for up to ~45 s, so a freshly provisioned proxy that is still being routed passes without caller-side retries. If the precheck still fails, the error tells you why:
  • 409 CONNECT_PROXY_NOT_ACTIVE — the proxy is not (or no longer) serving traffic, e.g. still provisioning. Transient while provisioning: retry in a few seconds.
  • A denial that keeps failing while the proxy is active usually means the organization is out of prepaid proxy data — but the gateway returns the same denial for short internal hiccups, so it surfaces as a generic error rather than a billing one. Check your proxy data balance if retries keep failing.
Pass exactly one of id or country, and don’t combine connect with socks5 or the legacy flat fields. smartIp works with all variants. A proxy provisioned via country stays with the device and is cancelled automatically when the device is terminated. Proxies referenced by id are never cancelled by this API. With smartIp: true, the API geolocates the proxy’s exit IP through the proxy itself and aligns the device to match — GPS location, time zone, locale, and (unless an eSIM is active) mobile carrier and network type.
A smart IP failure leaves your existing proxy untouched, but a failure while connecting the new proxy can leave the device with no proxy at all. Check the proxy state before retrying.
On fleetd devices, an upstream switch on an already-proxied device applies live with no interruption, but the first time a device gets a proxy the device restarts to pick it up.

Authorizations

Authorization
string
header
required

Bearer token via Authorization header

Headers

X-Device-Display-ID
integer<int64>
default:0
Required range: x >= 0

Path Parameters

deviceId
string
required

Body

application/json
connect
object

Mobilerun Connect proxy — pass exactly one of id (use an existing proxy's credentials) or country (provision or reuse a rotating residential proxy for the device).

host
string<hostname>
deprecated
Maximum string length: 255
name
string

Proxy name

Maximum string length: 255
password
string
deprecated
write-only
Maximum string length: 255
port
integer<int64>
deprecated
Required range: 1 <= x <= 65535
smartIp
boolean
socks5
object

SOCKS5 proxy configuration (required for socks5).

user
string
deprecated
Maximum string length: 255

Response

No Content