API reference

IncomingPhoneNumbers API

Provision, configure, and manage the phone numbers assigned to your account.

IncomingPhoneNumber resource

{
  "sid": "PN…",
  "account_sid": "AC…",
  "phone_number": "+23412000000",
  "friendly_name": "Support line",
  "voice_url": "https://app.example.com/twiml/inbound",
  "voice_method": "POST",
  "status_callback_url": "https://app.example.com/calls/status",
  "status_callback_method": "POST",
  "sms_url": "https://app.example.com/sms/inbound",
  "sms_method": "POST",
  "status": "active",
  "date_created": "…",
  "uri": "/2010-04-01/Accounts/AC…/IncomingPhoneNumbers/PN…"
}

Provision a number

POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers

Buy an available number and assign it to an account. Only carrier administrators can provision numbers.

Parameter	Type	Description
`PhoneNumber` required	`string`	The E.164 number to provision.
`FriendlyName` optional	`string`	A human-friendly label.
`VoiceUrl` optional	`string`	Inbound call handler (returns TwiML).
`VoiceMethod` optional	`string`	HTTP method for `VoiceUrl`.
`StatusCallbackUrl` optional	`string`	Call status webhook URL.
`StatusCallbackMethod` optional	`string`	HTTP method for the callback.
`SmsUrl` optional	`string`	Inbound SMS handler.
`SmsMethod` optional	`string`	HTTP method for `SmsUrl`.

List numbers

GET/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers

Parameter	Type	Description
`Page` optional	`integer`	0-indexed page.
`PageSize` optional	`integer`	Records per page (max 1000).

Update a number

POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

Reconfigure the number's handlers (VoiceUrl, SmsUrl, callbacks, friendly name).

Parameter	Type	Description
`FriendlyName` optional	`string`	A human-friendly label.
`VoiceUrl` optional	`string`	Inbound call handler (returns TwiML).
`VoiceMethod` optional	`string`	HTTP method for `VoiceUrl`.
`StatusCallbackUrl` optional	`string`	Call status webhook URL.
`StatusCallbackMethod` optional	`string`	HTTP method for the callback.
`SmsUrl` optional	`string`	Inbound SMS handler.
`SmsMethod` optional	`string`	HTTP method for `SmsUrl`.

Release a number

DELETE/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

Release the number, returning it to the available inventory. Inbound calls and messages will no longer be routed.

Response — 204 No Content

With the SDK

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

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

const numbers = await client.incomingPhoneNumbers.list({ accountSid: "AC…" });