Logo
Search
Docs

Purchase phone number

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

Purchase a phone number and register it unassigned

Authentication

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

Authorization: Bearer <YOUR_API_KEY>

Request body

phone_number string Required

E.164 number from GET /phone-numbers/available.

Validation: required|string|max:20|regex:/^\+[1-9]\d{1,14}$/
Stored in assistant_phone_number_configurations.phone_number
country_code string Optional Nullable

Optional ISO country code for the purchase.

Validation: nullable|string|max:2
name string Optional Nullable

Optional friendly label.

Validation: nullable|string|max:255
Stored in assistant_phone_number_configurations.name

Errors

StatusMeaningBody
422 Invalid E.164 or number already in account {"success":false,"message":"This phone number is already in your account."}
500 Purchase failed at the telephony provider {"success":false,"message":"Failed to purchase phone number: …"}
502 Purchased but voice-platform import failed {"success":false,"message":"Phone number was purchased but could not be registered on the voice platform. …"}
422 Validation failed {"message":"…","errors":{"field":["…"]}}
401 Missing or invalid bearer token
403 Feature phone_numbers not enabled for the account

Notes

  • Creates a configuration row with no inbound target — assign next with PUT /phone-numbers/{id}.
  • Confirm cost with the end user before calling; this incurs telephony spend.
curl --request POST \
  --url https://app.sulus.ai/api/phone-numbers \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "phone_number": "+14155551234",
  "country_code": "US",
  "name": "Main Line"
}'
import requests

url = "https://app.sulus.ai/api/phone-numbers"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "phone_number": "+14155551234",
  "country_code": "US",
  "name": "Main Line"
}

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

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

func main() {
	url := "https://app.sulus.ai/api/phone-numbers"
	payload := strings.NewReader(`{
  "phone_number": "+14155551234",
  "country_code": "US",
  "name": "Main Line"
}`)
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 201 
{
    "success": true,
    "message": "Phone number purchased. Assign it to an assistant or squad when ready.",
    "data": {
        "id": 7,
        "phone_number": "+14155551234",
        "vapi_phone_number_id": "c3d4e5f6-1a2b-4c3d-9e0f-1a2b3c4d5e6f",
        "assistant_id": null,
        "vapi_assistant_id": null,
        "vapi_squad_id": null,
        "vapi_workflow_id": null,
        "name": "Main Line",
        "provider": "twilio",
        "sms_enabled": false,
        "static_ip_enabled": false
    }
}