Numbers API

Numbers represent phone numbers (DIDs) that your agents use to make and receive calls. Each number can be assigned to a voice agent, text agent, and a SIP trunk.

Base URL: https://kalem.me/api/v1/numbers

The Number Object

{
  "id": 1,
  "number": "+15551234567",
  "provider": "manual",
  "status": "active",
  "voice_agent_id": 1,
  "voice_agent_name": "Sales Agent",
  "text_agent_id": null,
  "text_agent_name": null,
  "trunk_id": 1,
  "trunk_name": "Primary Trunk",
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:30:00+00:00"
}

List Numbers

GET /api/v1/numbers

Retrieve a paginated list of phone numbers for your account.

Query Parameters

Parameter	Type	Description
`search`	string	Search by phone number
`status`	string	Filter by `active` or `inactive`
`voice_agent_id`	integer	Filter by assigned voice agent
`trunk_id`	integer	Filter by SIP trunk
`per_page`	integer	Results per page (default: 15, max: 100)

Example Request

curl -X GET "https://kalem.me/api/v1/numbers?status=active" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const response = await fetch(
  'https://kalem.me/api/v1/numbers?status=active',
  { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Accept': 'application/json' } }
);
const data = await response.json();

import requests

response = requests.get(
    'https://kalem.me/api/v1/numbers',
    params={'status': 'active'},
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://kalem.me/api/v1/numbers', ['status' => 'active']);
$data = $response->json();

Create Number

POST /api/v1/numbers

Request Body Parameters

Parameter	Type	Required	Description
`number`	string	Required	Phone number in E.164 format (e.g., `+15551234567`)
`provider`	string	Optional	Provider: `manual`, `twilio`
`voice_agent_id`	integer	Optional	ID of the voice agent to assign
`text_agent_id`	integer	Optional	ID of the text agent to assign
`trunk_id`	integer	Optional	ID of the SIP trunk to assign

Example Request

curl -X POST https://kalem.me/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+15551234567",
    "provider": "manual",
    "voice_agent_id": 1,
    "trunk_id": 1
  }'

Get Number

GET /api/v1/numbers/{id}

curl -X GET https://kalem.me/api/v1/numbers/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Number

PUT /api/v1/numbers/{id}

Update a number's assigned agents or trunk. Partial updates are supported.

curl -X PUT https://kalem.me/api/v1/numbers/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"voice_agent_id": 2}'

Delete Number

DELETE /api/v1/numbers/{id}

curl -X DELETE https://kalem.me/api/v1/numbers/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Activate Number

POST /api/v1/numbers/activate

Activate an inactive number so it can receive and make calls.

Parameter	Type	Required	Description
`number`	string	Required	Phone number to activate

curl -X POST https://kalem.me/api/v1/numbers/activate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number": "+15551234567"}'

Deactivate Number

POST /api/v1/numbers/deactivate

Deactivate a number. The number will stop receiving and making calls.

curl -X POST https://kalem.me/api/v1/numbers/deactivate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number": "+15551234567"}'