---
title: "Release managed SMS number"
method: POST
path: "/v1/sms-numbers/{phone_number_id}/release"
tags: ["Credentials"]
---

# Release managed SMS number

`POST /v1/sms-numbers/{phone_number_id}/release`

## Request

- Base URL: `https://api.skyvern.com`
- URL: `https://api.skyvern.com/v1/sms-numbers/{phone_number_id}/release`
- Auth: API key in header `x-api-key`

For billing-exempt numbers, forwarding stops immediately. For numbers with a subscription, billing and forwarding continue until the current billing period ends. Skyvern then holds the number for 30 days before it can be reassigned.

## Path parameters

- `phone_number_id` string, required

## Response `200`

Successful Response

- OrganizationPhoneNumberResponse: Safe phone-number metadata without provider routing or cost secrets.
  - `phone_number_id` string, required
  - `organization_id` string, required
  - `sms_config_id` string, required
  - `phone_number` string, required
  - `provider` string, required
  - `credential_id` string, nullable
  - `price_cents` integer, nullable
  - `billing_exempt` boolean
  - `status` 'active' | 'disabled' | 'released' | 'quarantined' | 'provisioning' | 'quarantining' | 'releasing' | 'surrendering' | 'reversal_pending', required
  - `cancel_at` string, date-time, nullable
  - `quarantined_until` string, date-time, nullable
  - `created_at` string, date-time, required
  - `modified_at` string, date-time, required
  - `deleted_at` string, date-time, nullable

## Other responses

- `403`: Managed SMS numbers are not enabled for the organization
- `404`: The managed SMS number was not found
- `409`: The managed SMS number cannot be released in its current state
- `422`: Validation Error
- `502`: The phone number provider cleanup request failed
- `503`: Billing configuration, managed SMS configuration, or Stripe is unavailable

## Changes

- **2026-10-27** `dc7de12b8e80`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/changes/v1/sms-numbers/:phone_number_id/release/post.md)

---

[API](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2.md) - [All operations](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/revisions/64479cb160ff?raw)