# 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                                  |

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

```json
{
  "phone_numbers": [
    {
      "id": "pn_abc123",
      "number": "+2348012345678",
      "country": "NG",
      "type": "local",
      "status": "active",
      "endpoint_id": "ep_xyz789",
      "allow_inbound": true,
      "allow_outbound": true,
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-01-10T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

{% endtab %}
{% endtabs %}

#### Get Phone Number

Retrieve details for a specific phone number.

```
GET /phone-numbers/{id}
```

Request

{% code title="curl" %}

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

{% endcode %}

### Response

```json
{
  "id": "pn_abc123",
  "number": "+2348012345678",
  "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

{% code title="curl" %}

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

{% endcode %}

### Response

```json
{
  "available_numbers": [
    {
      "inventory_id": "inv_ng_001",
      "number": "+2348012345678",
      "country": "NG",
      "type": "local",
      "monthly_cost_cents": 500,
      "setup_cost_cents": 0,
      "capabilities": {
        "voice": true,
        "sms": false
      }
    },
    {
      "inventory_id": "inv_ng_002",
      "number": "+2348012345679",
      "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

{% code title="curl" %}

```bash
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
  }'
```

{% endcode %}

### Response

```json
{
  "id": "pn_abc123",
  "number": "+2348012345678",
  "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

{% code title="curl" %}

```bash
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
  }'
```

{% endcode %}

### Response

```json
{
  "id": "pn_abc123",
  "number": "+2348012345678",
  "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

{% code title="curl" %}

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

{% endcode %}

### Response

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

{% hint style="warning" %}
Releasing a number is immediate and cannot be undone. The number may be purchased by another customer.
{% endhint %}

## 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

{% tabs %}
{% tab title="TypeScript" %}
{% code title="examples.ts" %}

```typescript
// 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();
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="examples.py" %}

```python
import requests
import os

API_KEY = os.environ.get('KROSAI_API_KEY')
BASE_URL = 'https://api.krosai.com/v1'

def list_phone_numbers(country=None):
    params = {}
    if country:
        params['country'] = country
    
    response = requests.get(
        f'{BASE_URL}/phone-numbers',
        headers={'x-api-key': API_KEY},
        params=params
    )
    return response.json()

def purchase_number(inventory_id, endpoint_id=None):
    payload = {'inventory_id': inventory_id}
    if endpoint_id:
        payload['endpoint_id'] = endpoint_id
    
    response = requests.post(
        f'{BASE_URL}/phone-numbers',
        headers={
            'x-api-key': API_KEY,
            'Content-Type': 'application/json'
        },
        json=payload
    )
    
    if not response.ok:
        raise Exception(response.json().get('error'))
    
    return response.json()

def update_number(number_id, **config):
    response = requests.patch(
        f'{BASE_URL}/phone-numbers/{number_id}',
        headers={
            'x-api-key': API_KEY,
            'Content-Type': 'application/json'
        },
        json=config
    )
    return response.json()
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Next Steps

* [Create an Endpoint](/voice/endpoints.md) to route calls
* [Make Outbound Calls](/voice/outbound-calls.md)
* [View Call Logs](/voice/call-logs.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/numbers/buy-numbers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.