Buy Numbers
The Phone Numbers API lets you search for available numbers, purchase them, attach them to endpoints, and release them when no longer needed. This guide explains the core workflow and concepts. For full parameter schemas and response shapes, refer to the API Reference.
How It Works
Managing phone numbers follows a three-stage lifecycle:
1
Search Inventory
Query the available numbers inventory by country, number type (local, mobile, toll-free), and area code. Each result returns an inventory_id that you use in the next step.
2
Purchase & KYC
Submit the inventory_id to purchase the number. Some countries require Know Your Customer (KYC) verification before a number can be activated. If KYC has not been completed, the API returns a KYC_REQUIRED or KYC_PENDING error. Complete verification in the dashboard before retrying.
3
Attach to an Endpoint
Once purchased, route the number to an AI voice endpoint by supplying an endpoint_id — either at purchase time or later via an update. Inbound and outbound call permissions can be toggled independently.
Number Status
A phone number moves through the following statuses during its lifecycle:
| Number is being provisioned after purchase. |
| Number is fully operational and ready to handle calls. |
| Number is temporarily suspended, typically due to a billing or compliance issue. |
| Number is being ported in from another carrier. |
Available Endpoints
The table below lists all Phone Numbers endpoints. Click through to the API Reference for full parameter schemas, request/response examples, and error codes.
|
| Search purchasable numbers by country, type, and area code. |
|
| Purchase a number from inventory and optionally attach it to an endpoint. |
|
| List all phone numbers owned by your organisation, with optional status and country filters. |
|
| Retrieve details and current status for a specific number. |
|
| Update the endpoint routing or inbound/outbound call permissions for a number. |
|
| Release a number immediately. This action is irreversible — the number returns to the shared inventory. |
End-to-End Example
The snippet below shows the complete flow: search for an available number, purchase it, and attach it to an endpoint in a single sequence.
const API_KEY = process.env.KROSAI_API_KEY;
const BASE = 'https://api.krosai.com/api/v1';
const headers = {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
};
// 1. Search available numbers
const available = await fetch(`${BASE}/phone-numbers/available?country=NG&type=local`, { headers })
.then(r => r.json());
const { inventory_id } = available.data[0];
// 2. Purchase the number and attach to an endpoint
const purchased = await fetch(`${BASE}/phone-numbers`, {
method: 'POST',
headers,
body: JSON.stringify({ inventory_id, endpoint_id: 'ep_your_endpoint_id' })
}).then(r => r.json());
console.log('Number active:', purchased.phone_number);
Releasing a number is immediate and irreversible. The number returns to the shared inventory and may be purchased by another customer.
Next Steps
- Create an Endpoint to route calls to your AI agent.
On this page
- Buy Numbers