Copy page

Core Concepts

Phone Numbers

A phone number in Neuratel is a routing rule. It connects an inbound call from the public telephone network to a specific AI agent. When a caller dials a Neuratel number, the platform looks up the assigned agent, loads its configuration, and connects the caller directly into the conversation.

Phone numbers are also used as the outbound caller ID when an agent dials a customer — what the customer sees when their phone rings.

How Inbound Routing Works

When a call arrives on a Neuratel number:

1. The telephony infrastructure receives the inbound call and routes it to Neuratel's SIP ingress.
2. The platform looks up the phone number by its DID (direct inward dial) in E.164 format.
3. A dispatch rule routes the call to the assigned agent.
4. The agent's configuration is loaded — brain, voice, transcriber, conversation settings.
5. The caller hears the agent's first message and the conversation begins.

If no agent is assigned, the call cannot be connected.

Number Properties

Code
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "did": "+14155550123",
  "name": "Support Line",
  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "formatted_number": "+1 (415) 555-0123",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Field	Description
did	The phone number in E.164 format (e.g. +14155550123)
name	User-defined label for this number
agent_id	The agent currently assigned to handle calls on this number (null if unassigned)
is_active	Whether the number is active and accepting calls

Number Types

Type	Best For
Local	Regional presence — builds trust with local callers
Toll-Free	National presence — no cost to the caller

Coverage

Numbers are available across the US, Canada, UK, EU, and MENA regions. Contact your account team for specific country availability.

Getting Numbers

Number provisioning is handled by the Neuratel team as part of your setup.

To request a number: Contact support at [email protected] with your target country, area code preference, and number type.

To port an existing number: Contact support with your current provider's account details. Most ports complete in 3–7 business days.

Assigning a Number to an Agent

An unassigned number cannot receive calls. Assign an agent to activate routing.

Dashboard

1. Go to Numbers in the sidebar.
2. Click the edit icon next to the number.
3. Select an agent from the Assigned Agent dropdown.
4. Save.

API

Code
curl -X POST https://api.neuratel.ai/v1/numbers/{number_id}/assign \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "550e8400-e29b-41d4-a716-446655440000"}'

Code
import os, httpx

httpx.post(
    f"https://api.neuratel.ai/v1/numbers/{number_id}/assign",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
    json={"agent_id": "550e8400-e29b-41d4-a716-446655440000"},
)

Code
await fetch(`https://api.neuratel.ai/v1/numbers/${numberId}/assign`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEURATEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agent_id: "550e8400-e29b-41d4-a716-446655440000" }),
});

Unassigning a Number

Remove an agent assignment without deleting the number:

Code
curl -X POST https://api.neuratel.ai/v1/numbers/{number_id}/unassign \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
httpx.post(
    f"https://api.neuratel.ai/v1/numbers/{number_id}/unassign",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)

Code
await fetch(`https://api.neuratel.ai/v1/numbers/${numberId}/unassign`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});

List and Inspect Numbers

List All Numbers

Code
curl https://api.neuratel.ai/v1/numbers \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
response = httpx.get(
    "https://api.neuratel.ai/v1/numbers",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)
numbers = response.json()

Code
const response = await fetch("https://api.neuratel.ai/v1/numbers", {
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});
const numbers = await response.json();

Get a Specific Number

Code
curl https://api.neuratel.ai/v1/numbers/{number_id} \
  -H "Authorization: Bearer nk_live_your_api_key"

Update Number Name

Code
curl -X PUT https://api.neuratel.ai/v1/numbers/{number_id} \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Hotline"}'

Outbound Caller ID

When an agent makes an outbound call, the number_id field specifies which of your provisioned numbers is used as the caller ID.

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/outbound \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_number": "+14155551234",
    "number_id": "770e8400-e29b-41d4-a716-446655440002"
  }'

The number_id is required — it must match one of your provisioned phone numbers.

Compliance

STIR/SHAKEN — US numbers are registered and attested automatically. This reduces the likelihood of calls being labeled as spam.

Calling hours — Ensure your campaigns and outbound calls respect local regulations (e.g., 8 AM–9 PM local time for US FTC rules). Configure this in your campaign settings.

Do Not Call — You are responsible for scrubbing contact lists against applicable DNC registries before initiating outbound calls.

Troubleshooting

Number not receiving calls

• Confirm is_active is true.
• Confirm an agent is assigned (agent_id is not null).
• Confirm the number is_active: true.

Caller ID showing incorrectly

• Verify the did field is in correct E.164 format.
• Contact support if STIR/SHAKEN attestation needs correction.

---

Next Steps

• Agents — Configure agents to handle calls on your numbers
• Outbound Campaigns — Use numbers as caller ID in bulk campaigns
• Calls and Sessions — Understand the call lifecycle