Updating extra numbers

Update the alias (the name used in API calls) or the description of an extra number you already added, without recreating it. The number’s id stays the same.

Updating in the dashboard

Open the Numbers (opens in a new tab) page in the dashboard, open the number and edit the alias and/or the description. Save to apply the changes.

Updating through the API

Make a PATCH request with the number’s current alias (or its id) in the URL and, in the body, only the fields you want to change.

cURL

turbo-notify.sh

curl -X PATCH \
  https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "vendas_sp_2",
    "description": "São Paulo sales team (new shift)"
  }'

Node

turbo-notify.js

const response = await fetch('https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    alias: 'vendas_sp_2',
    description: 'São Paulo sales team (new shift)'
  })
});

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

Python

turbo_notify.py

import requests

url = "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS"
headers = {
    "Authorization": "Bearer YOUR_KEY",
    "Content-Type": "application/json"
}
data = {
    "alias": "vendas_sp_2",
    "description": "São Paulo sales team (new shift)"
}

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

Go

turbo_notify.go

package main

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

func main() {
    payload := strings.NewReader(`{"alias": "vendas_sp_2", "description": "São Paulo sales team (new shift)"}`)
    req, _ := http.NewRequest("PATCH", "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS", payload)
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

turbo-notify.php

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

$data = [
    'alias' => 'vendas_sp_2',
    'description' => 'São Paulo sales team (new shift)'
];

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer YOUR_KEY',
            'Content-Type: application/json'
        ],
        'method' => 'PATCH',
        'content' => json_encode($data)
    ]
];

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

C#

TurboNotify.cs

using System.Text;

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

var payload = new StringContent(
    "{\"alias\": \"vendas_sp_2\", \"description\": \"São Paulo sales team (new shift)\"}",
    Encoding.UTF8,
    "application/json"
);

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS")
{
    Content = payload
};
var response = await client.SendAsync(request);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

TurboNotify.java

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")
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(
                "{\"alias\": \"vendas_sp_2\", \"description\": \"São Paulo sales team (new shift)\"}"
            ))
            .build();

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

HTTP status: 200

{
  "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "alias": "vendas_sp_2",
  "description": "São Paulo sales team (new shift)",
  "status": "connected",
  "at": "2025-07-16T10:00:00Z",
  "scheduled_deletion_at": null
}

Required scope: numbers:write

The body fields are optional and independent: send only what you want to change.

Field	Type	Required	Description
alias	string	No	New alias of the number. Must start with a letter, be at most 50 characters and cannot be "main" or start with num_ (both reserved). Omit it to keep the current alias.
description	string | null	No	New description of the number. Send null explicitly to clear the current description; omit the field to leave it as is.

The response returns the updated state of the number:

Field	Type	Description
id	string	Identifier of the number (num_ and 32 characters), the same as before the update. It never changes.
alias	string	Current alias of the number (the new one, if it changed). Use it in the next calls to this number.
description	string | null	Current description of the number.
status	string	Current state of the number, see Status table.
at	string | null	When the number entered its current status (the same at as GET /v1/numbers/{ref}). Renaming does not change it. It is null while the number has no link yet.
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.

Renaming does not affect the connection

Changing the alias or the description does not disconnect the number, does not require pairing it again and does not restart it: the connection to WhatsApp stays exactly as it was. From the response on, use the new alias in any later call to this number.

The id is the stable key

Renaming the alias does not change the id. To find a customer’s number even after a rename, store the id and call GET /v1/numbers/{ref} with it. Events also carry number_id. An event’s number_alias shows the alias the number had when the event happened.

Main number

The main number cannot be changed: PATCH /v1/numbers/main answers 403 main_number_update_not_allowed for any body.

Possible errors

Status	Error code	Description
400	reserved_alias	The new alias is "main" or starts with num_, both reserved.
400	no_changes	No field was sent, or the only field sent (alias) is the same as the current value.
400	invalid_number_id	The value in the URL starts with num_ but is not a valid number id (num_ followed by 32 characters).
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:write scope (the response includes required_scope).
403	main_number_update_not_allowed	The main number (main) cannot be changed.
404	number_not_found	The alias or id in the path does not match any registered number.
409	alias_already_exists	Another extra number already uses that alias.
422	validation_error	alias is empty, does not start with a letter or is longer than 50 characters, or a text field contains an invalid character. The response includes details.errors with the specific field and message.
500	internal_error	Unexpected internal server error.