First call

By the end of this page you will have a valid token and a real response from the API. You will create the token in the panel and call a read endpoint.

Before you start

Only company administrators can create tokens. If the Integrations menu does not show up in the settings, ask whoever manages the account for the token.

The base URL is https://api.connectadesk.com/api/v1. If your company uses its own installation, replace it with that domain and keep the /api/v1 at the end.

Create the token in the panel

Go to Settings → Integrations → API and click New token. Fill in the fields:

Name: how you will recognize the token in the list. Use the name of the system that will use the API, not something like “token 1”.
Permissions: check only the modules and methods the integration needs. An external report, for example, only needs GET.
Expiry: set an expiry date whenever the integration is temporary.
Allowed IPs: if the system that will call the API has a fixed IP, restrict access to it. If left blank, the API accepts calls from any origin.

The full key appears only once, when the token is created. After that the panel shows only the prefix (sk_live_ab12cd34…). If you lose the key, there is no way to recover it. In that case, rotate the token.

Keep the key outside the code

export CONNECTA_TOKEN="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
export CONNECTA_URL="https://api.connectadesk.com/api/v1"

The key gives access to the whole company’s data, within the permissions you checked. Treat the key like a password and never put it in a repository, a log or the front-end.

Make the call

List the company’s contacts. Since it is a GET, nothing is changed, and the call confirms that the token, the host and the permission are correct.

curl --request GET \
  --url "$CONNECTA_URL/contacts?perPage=2" \
  --header "Authorization: Bearer $CONNECTA_TOKEN"

const res = await fetch(`${process.env.CONNECTA_URL}/contacts?perPage=2`, {
  headers: { Authorization: `Bearer ${process.env.CONNECTA_TOKEN}` }
});

const { data, meta } = await res.json();
console.log(data, meta);

import os, requests

res = requests.get(
    f"{os.environ['CONNECTA_URL']}/contacts",
    params={"perPage": 2},
    headers={"Authorization": f"Bearer {os.environ['CONNECTA_TOKEN']}"},
)

print(res.json())

$ch = curl_init(getenv('CONNECTA_URL') . '/contacts?perPage=2');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONNECTA_TOKEN')],
]);

echo curl_exec($ch);

Read the response

{
  "data": [
    {
      "id": 1042,
      "name": "Marina Alves",
      "number": "5511999999999",
      "email": "marina@exemplo.com.br",
      "isGroup": false,
      "tags": [{ "id": 3, "name": "Customer", "color": "#22C55E" }]
    },
    {
      "id": 1043,
      "name": "Rafael Nunes",
      "number": "5521988888888",
      "email": null,
      "isGroup": false,
      "tags": []
    }
  ],
  "meta": { "page": 1, "perPage": 2, "hasMore": true }
}

Records always come in data. On lists, meta tells you the current page and whether there are more records. The response does not include total. To go through everything, advance page while hasMore is true.

If the response was not 200

401 ERR_API_UNAUTHORIZED

The API returns the same 401 for a token that is missing, malformed, nonexistent, revoked, expired or used from an IP that is not among the allowed ones. For security reasons, the response does not say what the reason was.Check, in this order: whether the header is in the Authorization: Bearer sk_live_… format; whether the token is revoked or expired in the panel; and, if you set up allowed IPs, whether the call is coming from the expected IP.

403 ERR_API_FORBIDDEN_SCOPE

The token is valid, but it does not have permission for that method on that module. The error message tells you which combination was missing. Edit the token’s permissions in the panel. See Permissions.

403 ERR_API_NOT_ENABLED

The company’s plan does not include the public API. Talk to the sales team, because there is nothing to fix in the integration.

404 on everything

The cause is almost always the base URL without /api/v1 or the wrong host. The API returns the 404 in the same error envelope as the other responses (ERR_API_ROUTE_NOT_FOUND). If the body of the 404 came back as HTML, your call did not reach the API.

Next steps

Send a message

The full asynchronous flow, from the 202 to the confirmation that the message was sent.

Errors

The error envelope and what each code means.

Idempotency

How to repeat a call without duplicating the effect.

Reference

Every endpoint, with a playground to test in the browser.

Get started

Essentials

Guides

Before you start

If the response was not 200

Next steps

Send a message

Errors

Idempotency

Reference

​Before you start

​If the response was not 200

​Next steps

Send a message

Errors

Idempotency

Reference

Before you start

If the response was not 200

Next steps