Copy page

Guides

Setting Up Phone Numbers

Phone numbers connect your AI agents to callers. Neuratel supports local and toll-free numbers across the US, Canada, EU, UK, and MENA regions. This guide covers how to assign numbers to agents, configure outbound caller ID, and manage your number inventory.

Number Types

Local Numbers

Local numbers display a regional area code to callers, improving answer rates for outbound calls and providing a familiar presence for inbound support lines.

Attribute	Details
Format	E.164 — e.g. +14155551234
Best for	Regional businesses, local caller trust
Availability	US, Canada, UK, EU, and more

Toll-Free Numbers

Toll-free numbers are free for callers to dial and project a national, professional presence.

Attribute	Details
Format	800, 888, 877, 866, 855, 844, 833 prefixes
Best for	National support lines, high-volume inbound
Cost	Caller pays nothing; billed to your account

Getting Numbers

Phone numbers are provisioned by the Neuratel team as part of your onboarding.

To request additional numbers:

• Contact your account team or email [email protected]
• Specify your target country, area code preference, and number type (local or toll-free)

To port existing numbers:

• Contact support to initiate a port request with your current provider's account details
• Most ports complete in 3–7 business days

Assign a Number to an Agent

Each number maps to exactly one agent. Inbound calls to this number are answered by the assigned agent.

Code
curl -X POST https://api.neuratel.ai/v1/numbers/num_abc123/assign \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_xyz789"}'

Code
client.post("/v1/numbers/num_abc123/assign", json={"agent_id": "agent_xyz789"})

Unassign a Number

Remove the agent association. The number remains in your account but will not answer calls.

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

Update Number Name

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

Configure as Outbound Caller ID

Use one of your numbers as the displayed caller ID for outbound calls. When making API-initiated outbound calls, pass the number's id as number_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": "agent_xyz789",
    "to_number": "+12125550100",
    "number_id": "num_abc123"
  }'

List and Inspect Numbers

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

Response:

Code
{
  "results": [
    {
      "id": "num_abc123",
      "did": "+14155550101",
      "name": "West Coast Support",
      "agent_id": "agent_xyz789",
      "is_active": true,
      "formatted_number": "+1 (415) 555-0101",
      "created_at": "2025-04-07T10:00:00Z"
    }
  ],
  "metadata": { "total": 1, "page": 1, "limit": 20 }
}

Porting Existing Numbers

Bring your current business phone numbers to Neuratel without changing your published numbers.

Process:

1. Email [email protected] with the numbers to port and your current carrier
2. Complete the Letter of Authorization (LOA) we send you
3. We coordinate the transfer — typically 3–7 business days
4. Numbers appear in your dashboard once ported
5. Assign to agents immediately

Number porting has no downtime window. Calls continue routing through your existing carrier until the port completes.

API Reference

Endpoint	Method	Description
/v1/numbers	GET	List your numbers
/v1/numbers/{id}	GET	Get number details
/v1/numbers/{id}	PUT	Update number name
/v1/numbers/{id}/assign	POST	Assign an agent
/v1/numbers/{id}/unassign	POST	Remove agent assignment

Troubleshooting

Number not answering calls

• Confirm agent_id is set on the number
• Confirm the agent's status is active
• Confirm is_active is true on the number

Number shows as inactive

• Contact [email protected] if a number shows is_active: false

Next Steps

• Creating Outbound Campaigns — dial contacts at scale
• Building Your First Agent — configure the agent answering your number
• Production Checklist — verify everything before going live