Logo
Search
Docs

List phone numbers

GET https://app.sulus.ai/api/phone-numbers

List phone numbers you can access

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Query parameters

search string Optional Nullable
Validation: string (matches phone_number or name)
page integer Optional Default: 1
Validation: clamped to a minimum of 1
per_page integer Optional Default: 15
Validation: clamped between 1 and 100

Errors

StatusMeaningBody
401 Missing or invalid bearer token
403 Feature phone_numbers not enabled for the account

Notes

  • id is null for a row that has never been opened for editing — no configuration row has been materialised for it yet (purchased numbers already have an id).
  • unassigned is true when vapi_assistant_id, vapi_squad_id, and vapi_workflow_id are all empty.
  • name falls back to the owning assistant's name, then to the phone number itself, when no configuration row (or no name on it) exists.
  • When no configuration row exists yet, provider is filled with the platform default for telephony numbers (see the provider column default on the Database page).
  • Placeholder demo numbers are always excluded from this list.
curl --request GET \
  --url https://app.sulus.ai/api/phone-numbers \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
import requests

url = "https://app.sulus.ai/api/phone-numbers"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}

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

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

func main() {
	url := "https://app.sulus.ai/api/phone-numbers"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 200 
{
    "success": true,
    "data": [
        {
            "id": 7,
            "phone_number": "+14155551234",
            "vapi_assistant_id": "a1b2c3d4-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
            "vapi_squad_id": null,
            "vapi_workflow_id": null,
            "name": "Front Desk Line",
            "provider": "twilio",
            "sms_enabled": true,
            "unassigned": false,
            "assistant": {
                "name": "Front Desk"
            }
        },
        {
            "id": 8,
            "phone_number": "+14155557890",
            "vapi_assistant_id": null,
            "vapi_squad_id": null,
            "vapi_workflow_id": null,
            "name": "Spare Line",
            "provider": "twilio",
            "sms_enabled": false,
            "unassigned": true,
            "assistant": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 2,
        "from": 1,
        "to": 2
    }
}