Extra number status

Check the status of each extra number in your account to see whether it is connected and ready to send.

Check the status

To check the status of a specific extra number, make a GET request with the number’s alias or id.

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

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

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

import requests

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

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

package main

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

func main() {
    req, _ := http.NewRequest("GET", "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS", 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';

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

$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.GetAsync(
    "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS"
);
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"))
            .header("Authorization", "Bearer YOUR_KEY")
            .GET()
            .build();

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

Required scope: numbers:read

HTTP status: 200

{
  "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "contact_id": "ct_c7abb1f5ee9640bf86a0a20290810ae9",
  "name": "Condomínio Alpha",
  "type": "extra",
  "alias": "condominio_1",
  "number": "5511988887777",
  "status": "connected",
  "at": "2025-07-16T10:01:00Z",
  "description": null,
  "scheduled_deletion_at": null,
  "reason": null,
  "pairing": null
}

The main number has its own status route, GET /v1/numbers/main (same scope, numbers:read), with a shorter response: without the description, scheduled_deletion_at, reason and pairing fields, because the main number is paired only in the dashboard. The id also comes as the first field:

{
  "id": "num_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "contact_id": "ct_c7abb1f5ee9640bf86a0a20290810ae9",
  "name": "Laboratório Central",
  "type": "main",
  "alias": "main",
  "number": "5511973117056",
  "status": "connected",
  "at": "2026-04-07T10:00:00Z"
}

at follows the current status

at is the moment the number entered its current status: it updates on every transition (pairing, connection, connection drop, reconnection, failure, revocation). A disconnected, failed, reconnecting (and so on) number reports the moment of that transition, so disconnected since {at} / failed at {at} show the right time directly.

During an automatic reconnection (the connection to WhatsApp dropped, or Turbo Notify moved the number’s connection internally), the status is reconnecting and at is the moment the number went offline, the same as the at of the number.disconnected webhook. If the number does not come back within about one minute, you receive the number.disconnected webhook with that same at. After a drop of the connection to WhatsApp, the status stays reconnecting while Turbo Notify tries to reconnect; only after an interruption on Turbo Notify’s side does it change to disconnected, with the same at. If the number comes back within the window, at becomes the moment it came back and no webhook is sent.

A newly added number (status: "pending") has the time it was added in at.

A scheduled deletion changes neither the status nor at: the number keeps its connection status, and the deletion date comes separately in scheduled_deletion_at.

Response fields

Field	Type	Description
`id`	string	Identifier of the number (`num_` and 32 characters). Generated by Turbo Notify, it never changes and stays the same if the alias is renamed
`contact_id`	string\|null	Public identifier (`ct_…`) of the number’s own contact; `null` until resolved
`name`	string\|null	Name of the number’s WhatsApp account (captured on connection); `null` until a connection has been established
`type`	string	`"extra"` for an extra number. If `{ref}` is the id of the main number, the response is the `GET /v1/numbers/main` one and `type` is `"main"`
`alias`	string	Unique identifier of the extra number in the account
`number`	string	Phone number in E.164 digits (no `+`)
`status`	string	Current status, see Status table
`at`	string	ISO 8601 timestamp of the moment the number entered its current status (`status`): updates on every transition.
`description`	string\|null	The description set for the number; `null` when not set
`scheduled_deletion_at`	string\|null	ISO 8601 timestamp of the scheduled removal (see Remove); `null` when no removal is scheduled. The number keeps working, with its usual `status`, until that date
`reason`	string\|null	Failure reason when `status` is `"failed"`, see Failure reasons; `null` in any other status
`pairing`	object\|null	The pairing code or QR code: present only while the number is `pairing` and the code or QR code is ready

Pairing block (`pairing`)

Present when status is pairing and the code or QR code is ready (see Pairing extra numbers with the API):

Field	Type	Description
`method`	string	Pairing method: `"pairing_code"` or `"qr"`
`data`	string	With `pairing_code`, the 8-character alphanumeric code to enter in WhatsApp (shown with a hyphen, e.g. `Z5X7-LTYL`). With `qr`, the QR code image as a PNG data URI (`data:image/png;base64,...`): use it as the `src` of an `<img>`, never as text
`expires_at`	string	ISO 8601 timestamp of when the whole attempt stops being usable, for both methods

Read method before showing data. WhatsApp renews the QR code on its own and Turbo Notify keeps data current: read again and replace the image on every read. The block disappears when the attempt ends. An integration that only handles codes must check method and, with "qr", not show data as text.

Status table

Status	Description
`pending`	Number registered; waiting for pairing to start.
`pairing`	Pairing in progress: the code or QR code is being generated or is waiting to be used in WhatsApp.
`inactive`	Authentication obtained, but the connection has not been established yet.
`connecting`	Connection being established (`POST .../connect` accepted).
`connected`	The number is linked and ready to send messages.
`disconnected`	Connection lost or turned off; authentication is kept so you can reconnect.
`reconnecting`	Turbo Notify is reconnecting the number on its own, after a connection drop or an internal move. You do not need to do anything. If the number does not come back within about one minute, you receive `number.disconnected` and Turbo Notify keeps trying; after a drop of the connection to WhatsApp, the status stays `reconnecting` while it tries.
`failed`	Pairing failed. The reason is in `reason`, see below.
`revoked`	The device was unlinked by WhatsApp.

Failure reasons

When status is "failed", the reason field tells you what happened, so you can show the right message to your customer. The same value arrives in the number.connect.failed event, which also carries a fixed sentence for each reason. In any other status, reason is null.

Reason	What happened and what to do
`pairing_timeout`	The code or QR code was generated but not used in time. Request a new code or QR code.
`paired_phone_mismatch`	Another WhatsApp used the code or scanned the QR code. Pair again using the phone of the registered number.
`phone_already_bound`	This number is already in use in the account.
`main_number_not_connected`	The account’s main number must be connected to pair extra numbers. Reconnect the main number and pair again.
`code_generation_failed`	The code or QR code could not be obtained from WhatsApp at that moment. Try again shortly.
`connection_lost`	The number lost its connection to WhatsApp and needs to be paired again.
`pairing_failed`	Any other failure. Pair again.

New reasons may be added. Treat a value you do not recognize as pairing_failed. To build your customer’s pairing screen, see Pairing extra numbers with the API.

Possible errors

Status	Error code	Description
`402`	`feature_not_available`	The current plan does not support extra numbers.
`401`	`not_authenticated`	The API key is invalid or missing.
`403`	`insufficient_scope`	The API key does not have the `numbers:read` scope (the response includes `required_scope`).
`404`	`number_not_found`	The alias or id was not found in the account.
`500`	`internal_error`	Unexpected internal server error.