Phone Provisioning

Overview

Sulus provides a REST API endpoint to create (provision) phone numbers programmatically. You can create a free Sulus US number or import a number you already own from your own carrier account.

POST https://api.sulus.ai/phone-number

Include your Sulus API key in the Authorization header as a Bearer token:

Authorization: Bearer <your-api-key>

Create a free Sulus US number:

curl -X POST "https://api.sulus.ai/phone-number" \
  -H "Authorization: Bearer $SULUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sulus",
    "assistantId": "your-assistant-id",
    "numberDesiredAreaCode": "415"
  }'

TypeScript:

const res = await fetch('https://api.sulus.ai/phone-number', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SULUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'sulus',
    assistantId: 'your-assistant-id',
    numberDesiredAreaCode: '415',
  }),
});
const phoneNumber = await res.json();
console.log(phoneNumber.id);

Python:

import os, requests

res = requests.post(
    "https://api.sulus.ai/phone-number",
    headers={
        "Authorization": f"Bearer {os.getenv('SULUS_API_KEY')}",
        "Content-Type": "application/json",
    },
    json={
        "provider": "sulus",
        "assistantId": "your-assistant-id",
        "numberDesiredAreaCode": "415",
    },
    timeout=30,
)
phone_number = res.json()
print(phone_number["id"])

• Free numbers are only available for US national use.
• Each account can have up to 10 free numbers.
• It takes a couple of minutes for a newly created number to be fully activated — calls will not be functional during this period.
• For international numbers, you must import your own number from a supported external carrier using the /phone-numbers/import endpoint.
• Once created, you can attach an assistantId to the number so it automatically handles inbound calls with that assistant.

In summary, Sulus's phone number API lets you provision a free US number instantly for testing or light use, or import your own number from a supported external carrier for international or custom configurations. Once created, attaching an assistant to the number makes it ready to handle inbound calls.