List SMS phone numbers

GET/api/v1/sms/numbers

GET /sms/numbers

curl -X GET 'https://www.unitpost.com/api/v1/sms/numbers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Response · 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_number",
      "id": "id_123",
      "phone_number": "string",
      "type": "toll_free",
      "status": "pending",
      "is_default": false,
      "country": "string",
      "reach": [
        "string"
      ],
      "brand_id": "brand_123",
      "use_case": {
        "name": "Example",
        "category": "string"
      },
      "action_required_reason": "string",
      "sender_id_group": {
        "name": "Example",
        "brand_id": "brand_123",
        "countries": [
          {
            "country": "string",
            "status": "pending"
          }
        ]
      },
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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.

Parameters3 fields

Field	Type	Description
`limit`	integer · query	Max rows to return (default 20, max 100).
`after`	string · query	Return rows after this id (forward paging).
`before`	string · query	Return rows before this id (backward paging).

Response · 200 fields13 fields

Field	Type	Description
`object`required	string	—
`id`required	string	Prefixed number id, e.g. `snum_…`.
`phone_number`required	object	E.164 number. Null while a 10DLC registration is still in review — the number is assigned on approval.
`type`required	enumtoll_free \| ten_dlc \| long_code \| sender_id \| simulator	`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`required	enumpending \| action_required \| active \| rejected \| released	Only `active` numbers can send.
`is_default`required	boolean	—
`country`required	object	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`required	string[]	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`required	object	The brand this number is registered under.
`use_case`required	object	What carriers approved this number to send. Required for approval; submitted with the number.
`action_required_reason`required	object	Set when status is `action_required` or `rejected`.
`sender_id_group`required	object	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.
`created_at`required	string	—

200401403404422

List SMS phone numbers

List SMS phone numbers

Search docs and guides