---
title: "List SMS phone numbers"
method: GET
path: "/sms/numbers"
tags: ["SMS"]
---

# List SMS phone numbers

`GET /sms/numbers`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/sms/numbers`
- Auth: HTTP bearer

Retrieve your SMS sending identities: phone numbers and alphanumeric Sender IDs. Only entries with `status: "active"` can send; a `ten_dlc` number has no `phone_number` until carriers approve the registration, a `long_code` is a local number issued outside the US (Canada today: `country: "CA"`, `reach: ["CA"]`, no carrier registration, `use_case: null`), and a `simulator` number only delivers to verified test destinations. `use_case` is what carriers approved the number to send. A `sender_id` entry is one country of a Sender ID: the identity is ONE string per brand enabled per country, the list returns one entry per (Sender ID, country), and every entry carries `sender_id_group` with the whole country set so you can group them. Requesting or releasing an identity is only available in the dashboard. Requires the `sms:read` capability.

## Query parameters

- `limit` integer
- `after` string
- `before` string

## Response `200`

A page of SMS phone numbers.

- object
  - `object` 'list', required
  - `has_more` boolean, required
  - `data` SmsNumber[], required
    - `object` 'sms_number', required
    - `id` string, required: Prefixed number id, e.g. `snum_…`.
    - `phone_number` string, nullable, required: E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval.
    - `type` 'toll_free' | 'ten_dlc' | 'long_code' | 'sender_id' | 'simulator', required: `long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender.
    - `status` 'pending' | 'action_required' | 'active' | 'rejected' | 'released', required: Only `active` numbers can send.
    - `is_default` boolean, required: Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
    - `country` string, nullable, required: ISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded.
    - `reach` string[], required: ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown.
    - `brand_id` string, nullable, required: The brand this number is registered under.
    - `use_case` object, nullable, required: What carriers approved this number to send. Required for approval; submitted with the number.
      - `name` string, required
      - `category` string, nullable, required
    - `action_required_reason` string, nullable, required: Set when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`.
    - `sender_id_group` object, nullable, required: Present on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set.
      - `name` string, required: The Sender ID string recipients see.
      - `brand_id` string, nullable, required: The brand that owns this Sender ID.
      - `countries` object[], required: Every country this Sender ID is enabled for, with each country's own status.
        - `country` string, required: ISO-3166 alpha-2.
        - `status` 'pending' | 'action_required' | 'active' | 'rejected' | 'released', required
    - `created_at` string, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Insufficient scope.
- `404`: SMS is not enabled for this workspace.
- `422`: Invalid pagination params.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)