Retrieve an SMS number

GET/api/v1/sms/numbers/{id}

GET /sms/numbers/{id}

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

Response · 200

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

One number or one country of a Sender ID (snum_…), read as List SMS numbers reads it: its status, what carriers sent back (feedback) and its use case. Read a resubmit, a retry or a release back with it. Requires the sms:read capability.

Parameters1 field

Field	Type	Description
`id`required	string · path	—

Response · 200 fields15 fields

Field	Type	Description
`object`required	string	—
`id`required	string	Prefixed number id, e.g. `snum_…`.
`phone_number`required	string \| null	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	Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
`country`required	string \| null	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.
`two_way`required	boolean	Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
`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	string \| null	The brand this number is registered under.
`use_case`required	object \| null	What carriers approved this number to send. Required for approval; submitted with the number.
`action_required_reason`required	string \| null	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`.
`feedback`	object[] \| null	What carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159).
`sender_id_group`required	object \| null	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

Retrieve an SMS number

Retrieve an SMS number

Search docs and guides