Phone Numbers

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

Number Types

List Available Numbers

Browse inventory before provisioning.

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

Response:

1
{
2
  "numbers": [
3
    {
4
      "number_id": "num_abc123",
5
      "e164": "+2348031234567",
6
      "type": "mobile_virtual",
7
      "status": "available",
8
      "channels": ["voice"],
9
      "mno": "mtn"
10
    }
11
  ],
12
  "next_page_token": "..."
13
}

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.

$
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):

1
{
2
  "number_id": "num_abc123",
3
  "e164": "+2348031234567",
4
  "type": "mobile_virtual",
5
  "status": "provisioned",
6
  "agent_id": "agt_XXXX_xxxxxxxxxxxx",
7
  "channels": ["voice"],
8
  "mno": "mtn",
9
  "provisioned_at": "2026-04-09T10:00:00Z"
10
}

Auto-Provision a Number

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

$
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:

$
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:

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

Get a Single Number

$
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.

$
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:

$
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:

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:

• 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.