> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Phone Numbers

> Provision Nigerian DIDs, mobile virtual numbers, and international numbers for your agents.

Voicebip provides instant provisioning of Nigerian and international phone numbers from Temlio's NCC-licensed inventory.

## Number Types

| Type             | Prefix                           | Description                                         |
| ---------------- | -------------------------------- | --------------------------------------------------- |
| `geo_did`        | 01 (Lagos), 09 (Abuja), 084 (PH) | Nigerian geographic DID                             |
| `mobile_virtual` | 0803, 0805, 0802, 0809           | Nigerian mobile virtual (MTN, Glo, Airtel, 9mobile) |
| `intl_did`       | +44, +1                          | International DID (UK, US)                          |
| `shortcode`      | —                                | Short codes (future)                                |

## List Available Numbers

Browse inventory before provisioning.

```bash
curl "https://api.voicebip.com/v1/numbers/available?type=mobile_virtual&country_code=NG" \
  -H "Authorization: Bearer pk_live_xxx"
```

**Response:**

```json
{
  "numbers": [
    {
      "number_id": "num_abc123",
      "e164": "+2348031234567",
      "type": "mobile_virtual",
      "status": "available",
      "channels": ["voice"],
      "mno": "mtn"
    }
  ],
  "next_page_token": "..."
}
```

Filter by `type`, `country_code`, and optionally `area_code` (for geo_did).

## Provision a Number

Claim a number and bind it to an agent in a single API call. Completes in under 2 seconds.

```bash
curl -X POST "https://api.voicebip.com/v1/numbers" \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "num_abc123",
    "agent_id": "agt_XXXX_xxxxxxxxxxxx",
    "channels": ["voice"]
  }'
```

**Response (201):**

```json
{
  "number_id": "num_abc123",
  "e164": "+2348031234567",
  "type": "mobile_virtual",
  "status": "provisioned",
  "agent_id": "agt_XXXX_xxxxxxxxxxxx",
  "channels": ["voice"],
  "mno": "mtn",
  "provisioned_at": "2026-04-09T10:00:00Z"
}
```

## Auto-Provision a Number

Skip the browse-and-pick flow. Auto-provision picks the first available number matching your criteria:

```bash
curl -X POST "https://api.voicebip.com/v1/numbers/auto" \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_XXXX_xxxxxxxxxxxx",
    "type": "mobile_virtual",
    "country_code": "NG",
    "channels": ["voice"]
  }'
```

Returns the same `201` response as manual provisioning.

## List Provisioned Numbers

Retrieve all numbers your workspace currently owns:

```bash
curl "https://api.voicebip.com/v1/numbers?page_size=20" \
  -H "Authorization: Bearer pk_live_xxx"
```

Filter by `agent_id` to find numbers assigned to a specific agent:

```bash
curl "https://api.voicebip.com/v1/numbers?agent_id=agt_XXXX_xxxxxxxxxxxx" \
  -H "Authorization: Bearer pk_live_xxx"
```

## Get a Single Number

```bash
curl "https://api.voicebip.com/v1/numbers/num_abc123" \
  -H "Authorization: Bearer pk_live_xxx"
```

## Release a Number

Released numbers enter a 30-day quarantine period (NCC compliance) before returning to the available pool.

```bash
curl -X DELETE "https://api.voicebip.com/v1/numbers/num_abc123" \
  -H "Authorization: Bearer pk_live_xxx"
```

## Reclaim a Quarantined Number

If you released a number within the last 30 days, you can reclaim it before it returns to the shared pool:

```bash
curl -X POST https://api.voicebip.com/v1/numbers/num_xxx/reclaim \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agt_xxx"}'
```

The number must still be in quarantine and must have been owned by your workspace. Channels default to `["voice"]` if not specified.

## MNO Coverage

Every Nigerian mobile virtual number is routed through the appropriate MNO:

| MNO     | Prefixes                                       |
| ------- | ---------------------------------------------- |
| MTN     | 0803, 0806, 0703, 0706, 0813, 0816, 0810, 0814 |
| Glo     | 0805, 0807, 0705, 0815, 0811                   |
| Airtel  | 0802, 0808, 0708, 0812                         |
| 9mobile | 0809, 0817, 0818, 0908, 0909                   |

Outbound calls and SMS are routed to the correct MNO automatically with failover: MTN -> Glo -> Airtel -> 9mobile.

## Channel Types

Each number is assigned one or more channels at provisioning time (the `channels` array). Which channels a number supports depends on its type:

| Number type      | Supported channels |
| ---------------- | ------------------ |
| `geo_did`        | `voice`            |
| `mobile_virtual` | `voice`, `sms`     |
| `intl_did`       | `voice`            |
| `shortcode`      | `sms`              |

* **voice** -- Receives inbound calls, makes outbound calls
* **sms** -- Sends and receives SMS messages
* **whatsapp** -- WhatsApp messaging (Phase 2). WhatsApp is enabled separately from the base channel validation.

Requesting a channel that the number type does not support is rejected with `422`. A `mobile_virtual` number can serve both `voice` and `sms` at once — pass `["voice", "sms"]` in the `channels` array.