---
title: "Propose Phone Number Provision"
method: POST
path: "/v1/teams/{team_id}/phone/numbers/provisions"
tags: ["phone numbers"]
---

# Propose Phone Number Provision

`POST /v1/teams/{team_id}/phone/numbers/provisions`

## Request

- Base URL: `https://api.stormy.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stormy.ai/v1/teams/{team_id}/phone/numbers/provisions`
- Auth: none declared

Freeze one exact number purchase behind Stormy's normal action policy.

## Path parameters

- `team_id` string, uuid, required

## Headers

- `authorization` string, nullable
- `x-darwin-token` string, nullable
- `x-darwin-run-id` string, nullable

## Request body

- ProvisionPhoneNumberRequest: One exact provider-search result to freeze as a governed purchase.
  - `connection_id` string, uuid, required
  - `phone_number` string, required
  - `display_name` string, required
  - `monthly_price` object, required
  - `country_code` string
  - `number_type` 'local' | 'toll-free' | 'toll_free' | 'mobile'
  - `address_sid` string, nullable
  - `bundle_sid` string, nullable
  - `identity_sid` string, nullable
  - `recording_enabled` boolean, nullable
  - `voice` string, nullable
  - `language` string, nullable
  - `work_item_id` string, uuid, nullable
  - `purpose` string, nullable
  - `idempotency_key` string, nullable
  - `decide_by` string, date-time, nullable
  - `human_message` string, nullable

## Response `202`

Successful Response

- object

## Other responses

- `422`: Validation Error

## Changes

> 70 revisions in range; 1 not diffed.

- **2026-09-11** `79b0c0f35170`: 1 info
  - added the new optional request property `human_message`

[Operation history](https://skmtc.dev/stormy/apis/stormy-control-plane/changes/v1/teams/:team_id/phone/numbers/provisions/post.md)

---

[API](https://skmtc.dev/stormy/apis/stormy-control-plane.md) · [All operations](https://skmtc.dev/stormy/apis/stormy-control-plane/llms.txt) · [OpenAPI document](https://skmtc.dev/stormy/apis/stormy-control-plane/revisions/4d811ab18158?raw)