Connecting extra numbers

Disconnect an extra number that is already paired to stop using it for a while, and reconnect it whenever you want to come back, without pairing again. Disconnected numbers stay registered in the account, but cannot be used as a sender. For the first link to WhatsApp, see pairing in the dashboard or through the API.

Billing

Disconnected extra numbers keep being charged while they are registered. To stop the charge, you need to remove the number. See the details in Extra number billing.

In the dashboard

Open the Numbers (opens in a new tab) page in the dashboard to disconnect or reconnect numbers with one click.

Reconnect

To reconnect a disconnected extra number, make a POST request to the connect endpoint with the number’s alias in the URL.

curl -X POST \
  https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect \
  -H "Authorization: Bearer YOUR_KEY"

const response = await fetch('https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_KEY'
  }
});

const result = await response.json();
console.log(result);

import requests

url = "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect"
headers = {
    "Authorization": "Bearer YOUR_KEY"
}

response = requests.post(url, headers=headers)
result = response.json()
print(result)

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect", nil)
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$url = 'https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect';

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer YOUR_KEY'
        ],
        'method' => 'POST'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response);
?>

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");

var response = await client.PostAsync(
    "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect",
    null
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import java.net.http.*;
import java.net.URI;

public class TurboNotify {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/connect"))
            .header("Authorization", "Bearer YOUR_KEY")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

HTTP status: 202

{
  "alias": "vendas_sp",
  "status": "connecting",
  "at": "2026-06-01T12:40:00Z"
}

The response (202 Accepted) only confirms that the request was accepted: status is connecting and at is the moment the request was accepted. The number connects a few seconds later. The final status (connected or failed) arrives through the number.connected / number.connect.failed webhook, or by checking Extra number status, which stays the source of the number’s current status and of its own at.

Disconnect

To disconnect a connected extra number, make a POST request to the disconnect endpoint with the number’s alias in the URL.

curl -X POST \
  https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect \
  -H "Authorization: Bearer YOUR_KEY"

const response = await fetch('https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_KEY'
  }
});

const result = await response.json();
console.log(result);

import requests

url = "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect"
headers = {
    "Authorization": "Bearer YOUR_KEY"
}

response = requests.post(url, headers=headers)
result = response.json()
print(result)

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect", nil)
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$url = 'https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect';

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer YOUR_KEY'
        ],
        'method' => 'POST'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response);
?>

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");

var response = await client.PostAsync(
    "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect",
    null
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

import java.net.http.*;
import java.net.URI;

public class TurboNotify {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/disconnect"))
            .header("Authorization", "Bearer YOUR_KEY")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

HTTP status: 202

{
  "alias": "vendas_sp",
  "status": "disconnecting",
  "at": "2026-06-01T12:40:00Z"
}

disconnecting appears only in this response (202 Accepted), as a confirmation that the request was accepted, and at is the moment it was accepted. Unlike connecting, disconnecting is not one of the values in the Status table and does not appear in GET /v1/numbers/{ref} (which, right after this call, still shows the previous status and its own at until Turbo Notify finishes disconnecting). The final status (disconnected) arrives through the number.disconnected webhook, or by checking Extra number status.

The main number has its own routes, without {ref} in the path. The four routes on this page answer the same way: 202 Accepted with the fields alias, status and at, with the same meaning.

POST /v1/numbers/main/connect → 202 Accepted, {"alias": "main", "status": "connecting", "at": "2026-06-01T12:40:00Z"}
POST /v1/numbers/main/disconnect → 202 Accepted, {"alias": "main", "status": "disconnecting", "at": "2026-06-01T12:40:00Z"}

Neither depends on the plan. Both return 422 no_main_number_configured when the account has no main number. On connect: 422 main_number_not_paired when the number exists but has not finished pairing (pair it in the dashboard first), 409 already_connected and 409 already_connecting. On disconnect: 409 already_disconnected when the number is already disconnected (nothing to do, the goal is already met).

Possible errors

Reconnect (`POST /v1/numbers/{ref}/connect`)

Status	Error code	Description
`402`	`subscription_inactive`	The organization’s subscription is `past_due`, `terminated`, `pending` or its trial period has expired (the response includes `details.status`).
`402`	`feature_not_available`	The current plan does not support extra numbers.
`403`	`no_device_link`	The extra number has no active link to WhatsApp (inconsistent state).
`403`	`extra_number_not_paired`	The extra number has not finished pairing. Call `POST /v1/numbers/{ref}/pair` first.
`404`	`number_not_found`	The alias or id does not match any registered number.
`409`	`already_connected`	The extra number is already connected.
`409`	`already_connecting`	A connection attempt is already in progress.
`500`	`internal_error`	Unexpected internal server error.

Disconnect (`POST /v1/numbers/{ref}/disconnect`)

Status	Error code	Description
`402`	`feature_not_available`	The current plan does not support extra numbers.
`404`	`number_not_found`	The alias or id does not match any registered number.
`409`	`already_disconnected`	The extra number is already disconnected (nothing to do).
`500`	`internal_error`	Unexpected internal server error.

Both routes also return 401 not_authenticated (invalid or missing key) and 403 insufficient_scope (missing the numbers:write scope, the response includes required_scope) like any other authenticated endpoint.