Purchasing a Number

Surge supports three number types. Local and toll-free numbers are available via API. Short codes require a support request.

Prerequisites

Active account and API key: Both are required to call any phone number endpoint.
Plan that allows the number count you want: Hobby is capped at 1, Starter at 25, Growth and Custom are unlimited.
A campaign to attach to (eventually): Numbers can be purchased before a campaign is active, but they can’t send production traffic until they’re attached. See Attaching to a Campaign.

Number types

Type	Purchase path	Use case
Local	API	Standard SMS/MMS, most campaigns
Toll-free	API	High-volume transactional, customer care
Short code	Support	Very high-volume or marketing to large audiences

The dashboard at hq.surge.app walks you through the same purchase via UI, useful for one-off numbers or for confirming pricing and approval timelines: After choosing the type, the dashboard shows currently-available numbers with city/state for local numbers:

Numbers selected before your subscription is active

If you select a number in the dashboard before your subscription is active, Surge reserves it instead of purchasing it immediately. The dashboard lists it under Pending phone numbers with the note “These numbers will be purchased once your subscription is active.” Surge purchases all pending numbers automatically when your subscription becomes active. You don’t need to select the numbers again. If a pending number still hasn’t been purchased after your subscription activates, contact support.

Purchase a local number

Pass type: "local" and an area_code to find an available number in that area:

from surge import Surge

surge = Surge()

number = surge.phone_numbers.purchase(
    account_id="{account_id}",
    type="local",
    area_code="801",
)

import Surge from "@surgeapi/node";

const surge = new Surge();

const number = await surge.phoneNumbers.purchase("{account_id}", {
  type: "local",
  area_code: "801",
});

require "surge_api"

surge = SurgeAPI::Client.new

number = surge.phone_numbers.purchase(
  "{account_id}",
  type: "local",
  area_code: "801"
)

client = Surge.Client.new(System.get_env("SURGE_API_KEY"))

{:ok, number} =
  Surge.PhoneNumbers.purchase(client, "{account_id}", %{
    type: "local",
    area_code: "801"
  })

curl -X POST https://api.surge.app/accounts/{account_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "local",
    "area_code": "801"
  }'

{
  "id": "pn_01jrzhe8d9enptypyx360pcmxm",
  "number": "+18015559876",
  "type": "local",
  "campaign_id": null
}

If no numbers are available for the area code you specified, the API returns a no_matching_numbers error. Try a nearby area code or omit the area_code to get any available number. If your account has reached its phone number limit, the API returns a phone_number_limit error. Limits by plan:

Plan	Phone number limit
Hobby	1
Starter	25
Growth	Unlimited
Custom	Unlimited

Contact support to upgrade your plan if you need more numbers.

Purchase a toll-free number

number = surge.phone_numbers.purchase(
    account_id="{account_id}",
    type="toll_free",
)

const number = await surge.phoneNumbers.purchase("{account_id}", {
  type: "toll_free",
});

number = surge.phone_numbers.purchase(
  "{account_id}",
  type: "toll_free"
)

{:ok, number} =
  Surge.PhoneNumbers.purchase(client, "{account_id}", %{type: "toll_free"})

curl -X POST https://api.surge.app/accounts/{account_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "toll_free"
  }'

Toll-free numbers need to go through verification before they can send production traffic. See Toll-Free Verification.

List existing numbers

Retrieve all phone numbers on an account:

for number in surge.phone_numbers.list(account_id="{account_id}"):
    print(number.id, number.number)

for await (const number of await surge.phoneNumbers.list("{account_id}")) {
  console.log(number.id, number.number);
}

page = surge.phone_numbers.list("{account_id}")
page.data.each { |n| puts "#{n.id} #{n.number}" }

# Surge.PhoneNumbers.list isn't typed in the Elixir SDK yet — use the raw client.
{:ok, page} =
  Surge.Client.request(client, :get, "/accounts/{account_id}/phone_numbers")

Enum.each(page["data"], fn n -> IO.puts("#{n["id"]} #{n["number"]}") end)

curl https://api.surge.app/accounts/{account_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "pn_01jrzhe8d9enptypyx360pcmxm",
      "number": "+18015559876",
      "type": "local",
      "campaign_id": "cpn_01jrzhe8d9enptypyx360pcmxl"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null
  }
}

Attaching to a campaign

A freshly purchased number has campaign_id: null. Surge attaches phone numbers to campaigns automatically. You don’t call a separate endpoint. Two things trigger attachment:

Purchase while a campaign is active: Surge attaches the number immediately.
Campaign becomes active after purchase: Surge attaches all existing unattached numbers on the account when the campaign is approved.

When attachment completes, Surge fires a phone_number.attached_to_campaign webhook event. Once you receive that event, the number can send production traffic. See Attaching to a Campaign.

Short codes

Short codes (5-6 digit numbers like 12345) are available to all customers via a support request. They support very high message volumes and are the standard for large-scale marketing programs. Contact Surge support to start a short code request.

Get started

Register your business

Sending messages

Receiving messages & webhooks

Phone numbers

Verifications

Channels roadmap

Embeddable UI components

Concepts

Purchasing a Number

Prerequisites

Number types

Numbers selected before your subscription is active

Purchase a local number

Purchase a toll-free number

List existing numbers

Attaching to a campaign

Short codes

​Prerequisites

​Number types

​Numbers selected before your subscription is active

​Purchase a local number

​Purchase a toll-free number

​List existing numbers

​Attaching to a campaign

​Short codes

Prerequisites

Number types

Numbers selected before your subscription is active

Purchase a local number

Purchase a toll-free number

List existing numbers

Attaching to a campaign

Short codes