Get started →
Documentation

Phone numbers

Buy Nigerian local numbers, assign them to accounts, set monthly pricing, and manage the full lifecycle.

1. Search available numbers

List numbers available for purchase in a country and type (local, mobile, toll-free):

Examplets

const numbers = await client.availablePhoneNumbers.list({
  countryCode: "NG",
  type: "local",
  areaCode: "1",
  pageSize: 10,
});

for (const n of numbers) {
  console.log(n.phone_number, n.region, n.locality, n.price);
}

2. Buy a number

Purchase a number and assign it to an account:

Examplets

const incoming = await client.incomingPhoneNumbers.create({
  phoneNumber: "+23412000000",
  accountSid: "AC…",
  voiceUrl: "https://app.example.com/twiml/inbound",
  voiceMethod: "POST",
});

console.log(incoming.sid); // PN…
A number must belong to an account. Only carrier administrators can buy numbers; customers receive them via assignment.

3. Configure the number

Point the number at your application. Set the Voice URL (inbound TwiML), an SMS URL (inbound messages), or a ring group:

Examplets

const updated = await client.incomingPhoneNumbers.update("PN…", {
  voiceUrl: "https://app.example.com/twiml/inbound",
  voiceMethod: "POST",
  smsUrl: "https://app.example.com/sms/inbound",
  statusCallback: "https://app.example.com/calls/status",
});

Available configuration:

FieldPurpose
voiceUrl / voiceMethodInbound call handler (returns TwiML)
statusCallbackUrl / statusCallbackMethodCall status webhooks
smsUrl / smsMethodInbound SMS handler
messagingServiceIdAttach a messaging service for outbound SMS
ringGroupIdRoute inbound calls to a ring group

4. Set monthly pricing (for resellers)

As a carrier, you set the price customers pay each month via Phone Number Plans:

Examplets

await client.phoneNumberPlans.create({
  accountSid: "AC…",
  phoneNumber: "+23412000000",
  amount: "5000",
  currency: "NGN",
});

5. Lifecycle & release

  • Release a number to make it available again: client.incomingPhoneNumbers.remove("PN…")
  • List your account's numbers: client.incomingPhoneNumbers.list({ accountSid })
  • Status values: active, available, released.

Next