Skip to content

numbers.md

Latest commit

 

History

History
385 lines (292 loc) · 7.71 KB

numbers.md

File metadata and controls

385 lines (292 loc) · 7.71 KB
Raw

Numbers

Manage the phone numbers connected to your Texting Blue account. Each number is linked to an Apple device running the Texting Blue companion app.

Number Statuses

Status Description
active The number is connected and processing messages.
paused The number is temporarily stopped. No messages will be sent or received.

List Numbers

GET /v1/numbers

Permission: numbers:read

Returns all phone numbers associated with your account.

Response -- 200 OK

{
  "numbers": [
    {
      "id": "num_xxxxxxxxxxxx",
      "phone_number": "+14155559876",
      "label": "Sales Line",
      "status": "active",
      "verified": true,
      "device_name": "iPhone 15 Pro",
      "last_seen_at": "2026-02-07T11:58:00Z",
      "messages_today": 42,
      "created_at": "2026-01-15T09:00:00Z"
    },
    {
      "id": "num_yyyyyyyyyyyy",
      "phone_number": "+14155551111",
      "label": "Support",
      "status": "paused",
      "verified": true,
      "device_name": "iPhone 14",
      "last_seen_at": "2026-02-06T18:30:00Z",
      "messages_today": 0,
      "created_at": "2026-01-20T14:00:00Z"
    }
  ]
}

Examples

cURL

curl -X GET https://api.texting.blue/v1/numbers \
  -H "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Node.js

const response = await fetch("https://api.texting.blue/v1/numbers", {
  headers: {
    "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  },
});

const { numbers } = await response.json();
console.log(numbers.length); // 2

Python

import requests

response = requests.get(
    "https://api.texting.blue/v1/numbers",
    headers={"x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},
)

numbers = response.json()["numbers"]
print(len(numbers))  # 2

PHP

$ch = curl_init("https://api.texting.blue/v1/numbers");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$numbers = json_decode($response, true)["numbers"];
echo count($numbers); // 2

Get a Number

GET /v1/numbers/:id

Permission: numbers:read

Retrieve full details of a single phone number.

Response -- 200 OK

{
  "id": "num_xxxxxxxxxxxx",
  "phone_number": "+14155559876",
  "label": "Sales Line",
  "status": "active",
  "verified": true,
  "device_name": "iPhone 15 Pro",
  "last_seen_at": "2026-02-07T11:58:00Z",
  "messages_today": 42,
  "created_at": "2026-01-15T09:00:00Z"
}

Examples

cURL

curl -X GET https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx \
  -H "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Node.js

const response = await fetch(
  "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
  {
    headers: {
      "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    },
  }
);

const number = await response.json();
console.log(number.device_name); // "iPhone 15 Pro"

Python

import requests

response = requests.get(
    "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
    headers={"x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},
)

number = response.json()
print(number["device_name"])  # "iPhone 15 Pro"

PHP

$ch = curl_init("https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$number = json_decode($response, true);
echo $number["device_name"]; // "iPhone 15 Pro"

Update a Number

PUT /v1/numbers/:id

Permission: numbers:write

Update a number's label or status. Both fields are optional -- only include the fields you want to change.

Request Body

Field Type Required Description
label string No A friendly name for the number. Maximum 100 characters.
status string No Set to active or paused.

Response -- 200 OK

Returns the updated number object.

{
  "id": "num_xxxxxxxxxxxx",
  "phone_number": "+14155559876",
  "label": "Primary Sales",
  "status": "active",
  "verified": true,
  "device_name": "iPhone 15 Pro",
  "last_seen_at": "2026-02-07T11:58:00Z",
  "messages_today": 42,
  "created_at": "2026-01-15T09:00:00Z"
}

Examples

cURL

curl -X PUT https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx \
  -H "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Primary Sales",
    "status": "active"
  }'

Node.js

const response = await fetch(
  "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
  {
    method: "PUT",
    headers: {
      "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      label: "Primary Sales",
      status: "active",
    }),
  }
);

const number = await response.json();

Python

import requests

response = requests.put(
    "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
    headers={
        "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "Content-Type": "application/json",
    },
    json={"label": "Primary Sales", "status": "active"},
)

number = response.json()

PHP

$ch = curl_init("https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "label" => "Primary Sales",
    "status" => "active",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$number = json_decode($response, true);

Pausing a Number

Pause a number to temporarily stop all message processing:

curl -X PUT https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx \
  -H "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Delete a Number

DELETE /v1/numbers/:id

Permission: numbers:write

Remove a phone number from your account. This disconnects the number from Texting Blue. Messages in flight will still be delivered, but no new messages will be accepted.

Response -- 200 OK

{
  "deleted": true
}

Examples

cURL

curl -X DELETE https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx \
  -H "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Node.js

const response = await fetch(
  "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
  {
    method: "DELETE",
    headers: {
      "x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    },
  }
);

const { deleted } = await response.json();
console.log(deleted); // true

Python

import requests

response = requests.delete(
    "https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx",
    headers={"x-api-key": "tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},
)

print(response.json()["deleted"])  # True

PHP

$ch = curl_init("https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: tb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["deleted"]; // 1 (true)