Skip to main content

Phone Numbers

Phone numbers (DIDs) are assigned to accounts for inbound and outbound calling.

List Phone Numbers​

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

const response = await dialstack.phoneNumbers.list({ limit: 10, status: 'active' }, acct);

for (const phoneNumber of response.data) {
  console.log(phoneNumber.phone_number); // '+14155551234'
}

Parameters​

ParameterTypeDefaultDescription
limitnumber10Results per page (max 100)
statusstring-Filter by status: active, inactive, pending
dialstackAccountstringRequiredAccount ID

Response​

interface PhoneNumber {
  id: string;
  phone_number: string; // E.164 format (e.g., '+14155551234')
  status: 'active' | 'inactive' | 'pending';
  created_at: string;
}

Auto-Pagination​

Iterate All Phone Numbers​

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

for await (const pn of dialstack.phoneNumbers.list(undefined, acct).autoPagingEach()) {
  console.log(pn.phone_number, pn.status);
}

Collect to Array​

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

const allNumbers = await dialstack.phoneNumbers
  .list({ status: 'active' }, acct)
  .autoPagingToArray({ limit: 100 });

console.log(`Active phone numbers: ${allNumbers.length}`);

Examples​

Get Primary Phone Number​

async function getPrimaryPhoneNumber(accountId: string): Promise<string | null> {
  const acct = { dialstackAccount: accountId };

  const response = await dialstack.phoneNumbers.list({ limit: 1, status: 'active' }, acct);

  return response.data[0]?.phone_number ?? null;
}

Display Phone Numbers in UI​

async function getPhoneNumbersForDisplay(accountId: string) {
  const acct = { dialstackAccount: accountId };

  const phoneNumbers = await dialstack.phoneNumbers
    .list({ status: 'active' }, acct)
    .autoPagingToArray();

  return phoneNumbers.map((pn) => ({
    id: pn.id,
    display: formatE164(pn.phone_number), // '+1 (415) 555-1234'
    raw: pn.phone_number,
  }));
}

function formatE164(e164: string): string {
  const match = e164.match(/^\+1(\d{3})(\d{3})(\d{4})$/);
  if (match) {
    return `+1 (${match[1]}) ${match[2]}-${match[3]}`;
  }
  return e164;
}

Next Steps​