---
title: "List phone numbers"
method: GET
path: "/accounts/{account_id}/phone_numbers"
tags: ["Phone numbers"]
---

# List phone numbers

`GET /accounts/{account_id}/phone_numbers`

## Request

- Base URL: `https://api.surge.app`
- URL: `https://api.surge.app/accounts/{account_id}/phone_numbers`
- Auth: HTTP bearer

List all phone numbers for an account with cursor-based pagination.

## Path parameters

- `account_id` string, required: The account ID to list phone numbers for.

## Query parameters

- `after` string: Cursor for forward pagination. Use the next_cursor from a previous response.
- `before` string: Cursor for backward pagination. Use the previous_cursor from a previous response.

## Response `200`

List of phone numbers

- PhoneNumberList: A paginated list of phone numbers
  - `data` PhoneNumber[], required: The list of phone numbers
    - `campaign` PhoneNumberCampaign, required: Campaign attachment details for a domestic local phone number
      - `attachment_status` 'attached' | 'attachment_pending' | 'detached' | 'detachment_pending', required: The current campaign attachment status for this phone number.
      - `id` string, required: The unique identifier of the campaign this phone number is attached to
    - `campaign_id` string, nullable, required: Deprecated. The unique identifier of the campaign this phone number is attached to, if any
    - `id` string, required: Unique identifier for the phone number
    - `metadata` Metadata, required: Set of key-value pairs that will be stored with the object.
    - `name` string, nullable, required: A human-readable name for the phone number
    - `number` string, phone-number, required: The phone number in E.164 format
    - `type` 'local' | 'short_code' | 'toll_free', required: Whether the phone number is local, toll-free, or short code
  - `pagination` Pagination, required: Cursor-based pagination information
    - `next_cursor` string, nullable: Cursor for the next page of results. Null if there is no next page.
    - `previous_cursor` string, nullable: Cursor for the previous page of results. Null if there is no previous page.

## Other responses

- `default`: Error

## Changes

- **2026-10-16** `912b2a3101fc`: 1 info
  - added the required property `data/items/metadata` to the response with the `200` status
- **2026-07-14** `645782889002`: 2 info
  - response property `data/items/campaign_id` deprecated
  - added the required property `data/items/campaign` to the response with the `200` status
- **2026-04-22** `844ecbfa0d5b`: 1 info
  - added the required property `data/items/name` to the response with the `200` status
- **2026-03-11** `347377dfecf0`: 1 info
  - added the required property `data/items/campaign_id` to the response with the `200` status
- **2026-02-01** `f26f4552a4e2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/surgeapi/apis/surge/changes/accounts/:account_id/phone_numbers/get.md)

---

[API](https://skmtc.dev/surgeapi/apis/surge.md) - [All operations](https://skmtc.dev/surgeapi/apis/surge/llms.txt) - [OpenAPI document](https://skmtc.dev/surgeapi/apis/surge/revisions/bb534713d694?raw)