📞 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

Each dedicated number has a monthly rent charged against your organization’s monthly budget. Prices vary by country and number type — search results include a monthlyPrice field (USD). 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',
//     monthlyPrice: 0.5,
//     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 full monthly rent is charged immediately against your budget. The number is assigned to your account right away.

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 active phone numbers on 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.

Listing Released Numbers

Any released number — whether you released it manually or Pingram released it (e.g. failed monthly renewal or free-tier trial expiry) — is kept for reference but is not returned by the active list endpoint. You can purchase a released number again within two weeks of releasedAt; after that it may no longer be available and may be removed from this list.

const { numbers } = await pingram.numbers.listReleased();

console.log(numbers);
// [
//   {
//     phoneNumber: '+14155551234',
//     billingStatus: 'released',
//     releasedAt: '2024-02-15T00:00:05.123Z',
//     createdAt: '2024-01-15T10:30:00Z',
//     ...
//   }
// ]

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

Releasing a Number

Release a number you no longer need. The number is deactivated, marked released, and moved to the released list. No refund is issued for the current billing month.

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

console.log(result);
// { phoneNumber: '+14155551234', released: true, releasedAt: '2024-02-15T10:30:00.000Z' }

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 include one 7-day dedicated number trial per account. Paid accounts without approved A2P 10DLC registration are limited to one active number. With approved A2P registration, paid accounts can have 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.

Why was my number released?

Numbers are marked released when you release them yourself, when monthly fee cannot be deducted from your plan, or when a free-tier trial ends. Released numbers no longer appear in numbers.list() but are visible via numbers.listReleased(). Paid accounts can purchase a released number again within two weeks of releasedAt. Free accounts cannot order another dedicated number after the trial; upgrade to add numbers.

Do I get a refund if I release early?

No. You pay for the full month on purchase and each anniversary, with no prorated refunds on release.