Phone Numbers

Manage the iPhone numbers connected to your Texting Blue account.

List numbers

GET /v1/numbers

Returns all phone numbers registered to your team.

Required permission: numbers:read

Example

cURL

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

JavaScript

const response = await fetch('https://api.texting.blue/v1/numbers', {
  headers: { 'x-api-key': 'tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' },
});
const data = await response.json();
console.log(data.numbers);

Python

import requests

response = requests.get(
    'https://api.texting.blue/v1/numbers',
    headers={'x-api-key': 'tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'},
)
data = response.json()
for num in data['numbers']:
    print(f"{num['phone_number']} ({num['label']}) - {num['status']}")

Response

Status: 200 OK

{
  "numbers": [
    {
      "id": "num_xxxxxxxxxxxx",
      "phone_number": "+14155559876",
      "label": "Sales Line",
      "status": "active",
      "verified": true,
      "device_name": "John's iPhone",
      "last_seen_at": "2026-02-07T11:55:00Z",
      "messages_today": 42,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

---

Update a number

PUT /v1/numbers/:id

Update a number's label or status (pause/resume).

Required permission: numbers:write

Request body

Field	Type	Required	Description
label	string	No	Descriptive label (max 100 characters)
status	string	No	active or paused

Example

cURL

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

JavaScript

const response = await fetch('https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  },
  body: JSON.stringify({ label: 'Support Line', status: 'paused' }),
});

Python

import requests

response = requests.put(
    'https://api.texting.blue/v1/numbers/num_xxxxxxxxxxxx',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    },
    json={'label': 'Support Line', 'status': 'paused'},
)

Response

Status: 200 OK

{
  "id": "num_xxxxxxxxxxxx",
  "phone_number": "+14155559876",
  "label": "Support Line",
  "status": "paused",
  "verified": true
}

---

Start verification

POST /v1/numbers/verify

Initiate the verification process for a new phone number. Returns a setup URL that must be opened on the iPhone.

Required permission: numbers:write

Request body

Field	Type	Required	Description
phone_number	string	Yes	Phone number in E.164 format

Example

curl -X POST https://api.texting.blue/v1/numbers/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"phone_number": "+14155559876"}'

Response

Status: 200 OK

{
  "message": "Open this URL on the iPhone with this phone number to install the Texting Blue shortcut.",
  "setup_url": "https://app.texting.blue/setup-shortcut?token=dev_xxxxxxxxxxxx"
}

---

Delete a number

DELETE /v1/numbers/:id

Remove a phone number from your team. The device will stop polling.

Required permission: numbers:write

Example

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

Response

Status: 200 OK

{
  "deleted": true
}

---

Number statuses

Status	Description
active	Number is connected and processing messages
paused	Number is temporarily paused; no messages will be processed

The last_seen_at field indicates when the iPhone's shortcut last polled the server. If this timestamp is more than 5 minutes old, the device may be offline.

Next steps

• Webhooks -- Get notified about message events
• Managing numbers in the dashboard -- GUI guide