Release an SMS number

POST/api/v1/sms/numbers/{id}/release

POST /sms/numbers/{id}/release

curl -X POST 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/release' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'

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"
}

Give a toll-free, 10DLC or Canadian local number, or one country of a Sender ID, back to the carrier. PERMANENT: it stops sending at once, reads released from then on and can't be had back; its monthly fee ends with it (no proration). A 10DLC number's campaign registration goes with it. Refused while an automation uses it (resource_in_use) and, unless force, while campaigns are scheduled on it or texts are queued through it (sender_release_blocked, one error.details[] entry per kind of blocker). Works on any plan. Releasing an already released number answers it; the carrier finishes the release within minutes. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields

Field	Type	Description
`id`required	string · path	—
`Idempotency-Key`	string · header	Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.

Request body1 field

Field	Type	Description
`force`	boolean	Release although campaigns are scheduled on this number or texts are queued through it (the 409 `sender_release_blocked` lists them): those sends fail as "sender not active". An automation that uses the number still blocks the release (`resource_in_use`).

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	—

200400401403404409422429

Release an SMS number

Release an SMS number

Search docs and guides