---
title: "Retrieve an SMS number"
description: "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. `GET /api/v1/sms/numbers/{id}`"
url: https://www.unitpost.com/docs/sms/get-sms-numbers-id
section: "SMS API reference"
updated: 2026-11-11
---
# Retrieve an SMS number

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

One number or one country of a Sender ID (`snum_…`), read as [List SMS numbers](https://www.unitpost.com/docs/sms/get-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.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | Prefixed number id, e.g. `snum_…`. |
| `phone_number` | string \| null | yes | E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval. |
| `type` | enum | yes | `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. One of: `toll_free`, `ten_dlc`, `long_code`, `sender_id`, `simulator`. |
| `status` | enum | yes | Only `active` numbers can send. One of: `pending`, `action_required`, `active`, `rejected`, `released`. |
| `is_default` | boolean | yes | Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag. |
| `country` | string \| null | yes | 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` | boolean | yes | 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` | string[] | yes | 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 \| null | yes | The brand this number is registered under. |
| `use_case` | object \| null | yes | What carriers approved this number to send. Required for approval; submitted with the number. |
| `action_required_reason` | string \| null | yes | 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 | no | 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` | object \| null | yes | 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` | string | yes | — |

## Responses

| Status | Description |
| --- | --- |
| 200 | The number. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | Number not found, or SMS is not enabled. |
| 422 | An unknown query key. |

## Example request

```bash
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'
```

## Example response (200)

```json
{
  "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"
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/sms/get-sms-numbers-id
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json