Skip to main content
PUT
/
instances
/
{instanceId}
/
token
/
{token}
/
integrator
/
configure-proxy
Configure Proxy
curl --request PUT \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/integrator/configure-proxy \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "proxyUrl": "<string>",
  "enable": true
}
'

​
Overview

Method used to configure both the proxy URL and the option to enable proxy usage on the instance.
To use Partner endpoints, provide the Partner Token in the Authorization field, in the format: Bearer <Partner-Token>
The current values configured for proxyUrl and useProxy on the instance can be checked at the Instance Data endpoint.

​
Parameters

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Attributes

​
proxyUrl
string
required
Proxy URL to be used by the instance.
​
enable
boolean
required
Defines whether the configured proxy should be enabled (true) or disabled (false).
If the proxyUrl field is omitted or provided as an empty string, the instance’s current proxyUrl configuration will be replaced with an empty value.If the enable field is omitted or set to null, the instance’s existing enable configuration will be replaced with false.
If there is no proxyUrl configured, the enable field has no effect. The absence of a configured proxy URL will result in the instance connecting without using a proxy, regardless of the value of enable.

​
Request Body

{
  "proxyUrl": "socks5://user:password123@localhost:1080",
  "enable": true
}
If an error occurs while connecting using the configured proxy, 3 retry attempts will be made.If the connection fails on the third attempt, the instance is connected without using any proxy, and a webhook is triggered to the URL configured in the Proxy Failure Webhook.

​
Response

​
200

{
  "value": true
}

​
400

"Proxy is not reachable"
This error occurs when the connection test with the configured proxy fails. Check whether the provided proxy URL is correct and accessible.

​
401

This error occurs when the Partner Token provided in the Authorization field is empty or invalid.

​
405

In this case, make sure you are sending the correct method specification, i.e., check whether you sent the PUT request as specified at the beginning of this topic.

​
415

If you receive a 415 error, make sure to add the “Content-Type” header of the object you are sending in the request, in most cases “application/json”.