---
title: "Provision Phone Number"
method: POST
path: "/api/v1/phone/numbers"
tags: ["Phone Numbers"]
---

# Provision Phone Number

`POST /api/v1/phone/numbers`

## Request body

- ProvisionPhoneNumberRequest
  - `agent_handle` string, required — Agent identity handle to assign this number to (e.g. 'sales-agent' or '@sales-agent').
  - `type` 'local' | 'toll_free'
  - `state` string, nullable — US state abbreviation (e.g. 'NY', 'CA'). Only used for local numbers.
  - `incoming_call_action` 'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward'
  - `client_websocket_url` string, nullable — WebSocket URL (wss://) for audio bridging. Required when incoming_call_action is 'auto_accept'.
  - `incoming_call_webhook_url` string, nullable — Webhook URL for incoming call notifications. Required when incoming_call_action is 'webhook'.
  - `forwarding_target_type` 'phone' | 'sip'
  - `forwarding_phone_number` string, nullable — Phone number in E.164 format (e.g. '+15551234567').
  - `forwarding_sip_uri` string, nullable — Complete SIP destination in sip:user@host format.

## Response `201`

Successful Response

- PhoneNumberResponse
  - `id` string, uuid, required
  - `number` string, required
  - `type` 'local' | 'toll_free', required
  - `status` 'active' | 'paused' | 'released', required
  - `sms_status` 'pending' | 'ready' | 'assignment_failed', required
  - `sms_error_code` string, nullable
  - `sms_error_detail` string, nullable
  - `sms_ready_at` string, date-time, nullable
  - `incoming_call_action` 'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward', required
  - `client_websocket_url` string, nullable, required
  - `incoming_call_webhook_url` string, nullable, required
  - `forwarding_target_type` 'phone' | 'sip'
  - `forwarding_phone_number` string, nullable
  - `forwarding_sip_uri` string, nullable
  - `filter_mode` 'whitelist' | 'blacklist', required
  - `state` string, nullable — 2-letter US state abbreviation for LOCAL numbers (e.g. 'NY'). Null for toll-free numbers.
  - `agent_identity_id` string, uuid, nullable — ID of the agent identity that owns this phone number, or null if the number is standalone (not tied to any agent).
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `filter_mode_change_notice` FilterModeChangeNotice
    - `new_filter_mode` 'whitelist' | 'blacklist', required
    - `redundant_rule_action` string, required — 'block' or 'allow'; the action whose rules are now redundant.
    - `redundant_rule_count` integer, required — Count of active rules whose action equals redundant_rule_action. 0 = clean flip; >0 = console UI should prompt the operator to review.

## Other responses

- `422` — Validation Error
- `4XX` — Client error with Support Agent information.
- `5XX` — Server error with Support Agent information.

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)