> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remove SMS Number

> Release a toll-free number back to the carrier

# Remove SMS Number

Releases a toll-free number back to the carrier via Telnyx and frees its slot
under the workspace's 100-number cap. **This is irreversible** - once released,
the number cannot be reclaimed. Campaigns, sequence steps, and automations
still pinned to the released number will **skip their SMS sends** until you
point them at another verified number - an explicit "send from" choice is
never silently swapped for a different number. Sends that never picked a
specific number keep using the workspace default (oldest verified) number.

Use this when a number's verification was rejected and you want to purchase a
different one, or when a brand's number is no longer needed. This mutation
requires the `companies:manage` scope.

## Request

<ParamField path="numberId" type="string" required>
  The SMS number ID, as returned by [Get SMS
  Settings](/api-reference/sms/settings).
</ParamField>

No request body. Pass `X-Company-Id` if your API key has access to multiple
companies.

```bash theme={null}
curl --request DELETE "https://api.sequenzy.com/api/v1/sms/numbers/num_abc123" \
  --header "Authorization: Bearer $SEQUENZY_API_KEY"
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "number": {
      "id": "num_abc123",
      "status": "released"
    },
    "message": "SMS number released."
  }
  ```

  ```json 400 theme={null}
  {
    "error": "This number has already been released."
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "You have view-only access to this company. Contact the owner to request edit permissions."
  }
  ```

  ```json 404 theme={null}
  {
    "error": "SMS number not found"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "A number purchase is still in progress. Wait for it to finish before releasing."
  }
  ```

  ```json 500 theme={null}
  {
    "error": "Failed to release SMS number"
  }
  ```

  ```json 503 theme={null}
  {
    "error": "Failed to release the number with the carrier."
  }
  ```
</ResponseExample>