Buy Numbers

The Phone Numbers API allows you to purchase, configure, and manage local phone numbers for your AI voice agents.

List Phone Numbers

Retrieve all phone numbers owned by your organization.

GET /phone-numbers

Query Parameters

Parameter	Type	Description
status	string	Filter by status: active, suspended, pending
country	string	Filter by country code (e.g., NG, KE)
limit	integer	Number of results (default: 50, max: 100)
offset	integer	Pagination offset

Request

curl -X GET "https://api.krosai.com/v1/phone-numbers?country=NG&limit=10" \
  -H "x-api-key: kros_live_your_key"

Response

Get Phone Number

Retrieve details for a specific phone number.

GET /phone-numbers/{id}

Request

curl

curl -X GET "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "id": "pn_abc123",
  "number": "[phone]",
  "country": "NG",
  "type": "local",
  "status": "active",
  "endpoint_id": "ep_xyz789",
  "endpoint": {
    "id": "ep_xyz789",
    "name": "Support Agent",
    "type": "agent",
    "provider": "elevenlabs"
  },
  "allow_inbound": true,
  "allow_outbound": true,
  "monthly_cost_cents": 500,
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z"
}

List Available Numbers

Search for phone numbers available for purchase.

GET /phone-numbers/available

Query Parameters

Parameter	Type	Required	Description
country	string	Yes	ISO country code (e.g., NG, KE, AE)
type	string	No	Number type: local, mobile, toll_free
area_code	string	No	Specific area code
limit	integer	No	Number of results (default: 20)

Request

curl

curl -X GET "https://api.krosai.com/v1/phone-numbers/available?country=NG&type=local" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "available_numbers": [
    {
      "inventory_id": "inv_ng_001",
      "number": "[phone]",
      "country": "NG",
      "type": "local",
      "monthly_cost_cents": 500,
      "setup_cost_cents": 0,
      "capabilities": {
        "voice": true,
        "sms": false
      }
    },
    {
      "inventory_id": "inv_ng_002",
      "number": "[phone]",
      "country": "NG",
      "type": "local",
      "monthly_cost_cents": 500,
      "setup_cost_cents": 0,
      "capabilities": {
        "voice": true,
        "sms": false
      }
    }
  ],
  "total": 2
}

Purchase Phone Number

Purchase an available phone number.

POST /phone-numbers

Request Body

Field	Type	Required	Description
inventory_id	string	Yes	ID from available numbers list
endpoint_id	string	No	Endpoint to attach immediately
allow_inbound	boolean	No	Enable inbound calls (default: true)
allow_outbound	boolean	No	Enable outbound calls (default: true)

Request

curl

curl -X POST "https://api.krosai.com/v1/phone-numbers" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inventory_id": "inv_ng_001",
    "endpoint_id": "ep_xyz789",
    "allow_inbound": true,
    "allow_outbound": true
  }'

Response

{
  "id": "pn_abc123",
  "number": "[phone]",
  "country": "NG",
  "type": "local",
  "status": "active",
  "endpoint_id": "ep_xyz789",
  "allow_inbound": true,
  "allow_outbound": true,
  "monthly_cost_cents": 500,
  "created_at": "2025-01-10T10:00:00Z"
}

Error Responses

Status	Code	Description
400	KYC_REQUIRED	KYC verification not completed
400	KYC_PENDING	KYC verification still pending
400	INSUFFICIENT_BALANCE	Not enough credits
404	NUMBER_NOT_AVAILABLE	Number no longer available

Update Phone Number

Update phone number configuration.

PATCH /phone-numbers/{id}

Request Body

Field	Type	Description
endpoint_id	string	Endpoint ID to route calls to
allow_inbound	boolean	Enable/disable inbound calls
allow_outbound	boolean	Enable/disable outbound calls

Request

curl

curl -X PATCH "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_new456",
    "allow_inbound": true,
    "allow_outbound": false
  }'

Response

{
  "id": "pn_abc123",
  "number": "[phone]",
  "endpoint_id": "ep_new456",
  "allow_inbound": true,
  "allow_outbound": false,
  "updated_at": "2025-01-10T11:00:00Z"
}

Release Phone Number

Release a phone number. The number returns to the available pool.

DELETE /phone-numbers/{id}

Request

curl

curl -X DELETE "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "success": true,
  "message": "Phone number released successfully"
}

Releasing a number is immediate and cannot be undone. The number may be purchased by another customer.

Phone Number Status Values

Status	Description
active	Number is operational
suspended	Number is temporarily suspended
pending	Number is being provisioned
porting	Number is being ported

Code Examples

TypeScript

examples.ts

// List all phone numbers
async function listPhoneNumbers() {
  const response = await fetch('https://api.krosai.com/v1/phone-numbers', {
    headers: { 'x-api-key': process.env.KROSAI_API_KEY },
  });
  return response.json();
}

// Purchase a number
async function purchaseNumber(inventoryId: string, endpointId?: string) {
  const response = await fetch('https://api.krosai.com/v1/phone-numbers', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.KROSAI_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      inventory_id: inventoryId,
      endpoint_id: endpointId,
    }),
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }
  
  return response.json();
}

// Update number configuration
async function updateNumber(numberId: string, config: {
  endpoint_id?: string;
  allow_inbound?: boolean;
  allow_outbound?: boolean;
}) {
  const response = await fetch(
    `https://api.krosai.com/v1/phone-numbers/${numberId}`,
    {
      method: 'PATCH',
      headers: {
        'x-api-key': process.env.KROSAI_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(config),
    }
  );
  return response.json();
}

Python

Next Steps

• Create an Endpoint to route calls

• Make Outbound Calls

• View Call Logs