Purchasing a Number

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

Number types

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:

Purchase a local number

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

curl -X POST https://api.surge.app/accounts/YOUR_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:

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

Purchase a toll-free number

curl -X POST https://api.surge.app/accounts/YOUR_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:

curl https://api.surge.app/accounts/YOUR_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.