---
title: "Provision managed SMS number"
method: POST
path: "/v1/sms-numbers"
tags: ["Credentials"]
---

# Provision managed SMS number

`POST /v1/sms-numbers`

## Request

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

Purchase and configure a Skyvern-managed SMS number for the authenticated organization.

## Request body

- ProvisionManagedNumberRequest
  - `phone_number` 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

- `402`: Payment was declined or the billing account is ineligible or delinquent
- `403`: Managed SMS numbers are not enabled, the plan is not entitled, or the number cap is reached
- `409`: Another SMS number operation is in progress; retry later
- `422`: Validation Error
- `502`: The phone number provider request failed
- `503`: Billing configuration or Stripe is unavailable, or the payment outcome could not be confirmed

## Changes

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

[Operation history](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/changes/v1/sms-numbers/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)