📞 Managing Phone Numbers

Pingram provides APIs to search for available phone numbers, buy dedicated numbers for your account, and manage your number inventory.

Overview

Phone numbers in Pingram work in two tiers:

1. Shared Number - Every account has access to a shared Pingram number for sending SMS. This is available immediately with no setup required.
2. Dedicated Numbers - Purchase your own numbers for a consistent sender identity, better deliverability, and to receive inbound SMS.

Number Limits

Costs per number vary by region. See Pricing for details.

Searching for Available Numbers

Before buying, search for available numbers by country and optional filters.

const available = await pingram.numbers.searchAvailable({
  countryCode: 'US',
  areaCode: '415', // Optional: filter by area code
  features: 'sms,voice', // Optional: sms, voice, mms
  limit: 10 // Optional: max 50
});

console.log(available.numbers);
// [
//   {
//     phoneNumber: '+14155551234',
//     locality: 'San Francisco',
//     administrativeArea: 'CA',
//     phoneNumberType: 'local',
//     features: ['sms', 'voice', 'mms']
//   },
//   ...
// ]

Search Parameters

See the API Reference for examples in Python, Go, PHP, and other languages.

Buying a Number

Once you find a number, buy it with orderNumber. The number is immediately assigned to your account.

const order = await pingram.numbers.orderNumber({
  phoneNumber: '+14155551234'
});

console.log(order);
// {
//   orderId: 'ord_abc123',
//   status: 'success',
//   phoneNumber: '+14155551234'
// }

See the API Reference for examples in Python, Go, PHP, and other languages.

Listing Your Numbers

Retrieve all phone numbers associated with your account, plus the shared fallback number.

const { numbers, sharedNumber } = await pingram.numbers.list();

console.log(numbers);
// [
//   {
//     phoneNumber: '+14155551234',
//     createdAt: '2024-01-15T10:30:00Z',
//     label: 'Support Line'  // Optional label you've set
//   }
// ]

console.log(sharedNumber);
// '+18005550000' - The shared number available to all accounts

Response Fields

See the API Reference for examples in Python, Go, PHP, and other languages.

Using Your Numbers

Once you have a dedicated number, you can use it as the sender for SMS notifications:

await pingram.send({
  type: 'order_confirmation',
  to: {
    id: 'user_123',
    number: '+15005550006'
  },
  sms: {
    message: 'Your order #1234 has shipped!',
    from: '+14155551234' // Your dedicated number
  }
});

If you don’t specify a from number, Pingram uses:

1. Your dedicated number (if you have exactly one)
2. The shared number (if you have no dedicated numbers)

Receiving Inbound SMS

Dedicated numbers can receive inbound SMS messages. Configure a webhook to process incoming messages. See Inbound Messages for webhook setup and payload details.

FAQ

Why can I only buy one number?

Free accounts are limited to one phone number. Upgrade to a paid plan to purchase up to 49 numbers.

Why am I limited to one US number?

US carriers require A2P 10DLC registration for business SMS. Until your registration is approved, you’re limited to one US number. Once approved, you can purchase up to 49 US numbers. See A2P Registration to get started.

What’s the difference between dedicated and shared numbers?

Dedicated numbers are exclusively yours — you control the sender ID and can receive replies. The shared number is used by multiple Pingram customers and has lower throughput limits.

Can I port an existing number to Pingram?

Number porting is not currently supported. You’ll need to buy a new number through our search API.