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

12345678910const 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:

12345678const 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:

123456const 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:

Field	Purpose
`voiceUrl` / `voiceMethod`	Inbound call handler (returns TwiML)
`statusCallbackUrl` / `statusCallbackMethod`	Call status webhooks
`smsUrl` / `smsMethod`	Inbound SMS handler
`messagingServiceId`	Attach a messaging service for outbound SMS
`ringGroupId`	Route 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:

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

5. Lifecycle & release