---
title: "Request a managed Skysay phone number"
method: POST
path: "/v1/number-requests"
---

# Request a managed Skysay phone number

`POST /v1/number-requests`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/number-requests`
- Auth: none declared

## Request body

- ManagedNumberRequest
  - `agent_endpoint_id` string: Backwards-compatible alias for external audio agents.
  - `agent_id` string: The AI agent the number should answer with once it is active. Optional: when omitted, an activated number answers with the workspace's only active AI agent, and with nobody (an explicit do-not-answer rule) when there are several or none. A named agent that is no longer active is not replaced.
  - `carrier` string: Plain alias for provider; defaults to the platform's managed carrier.
  - `country` string, required: ISO country code or country name.
  - `customer_reference` string
  - `customer_type` string: business, individual, agent_builder, or internal.
  - `number_type` string: local, national, mobile, toll_free, shared_cost, or UIFN.
  - `organization_id` string, required
  - `preferred_phone_number` string: Optional customer preference. Until the carrier enables exact-number search, this does not reserve or promise a specific DID.
  - `project_id` string, required
  - `requested_capabilities` string[]

## Response `201`

Number request

## Other responses

- `409`: error inbound_coverage_missing: a confirmed purchase in a market Skysay cannot yet carry incoming calls for (blocker capacity_plan_unavailable or carrier_rate_missing). Refused before the request is created; nothing is charged.

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/95b8c66f99aa?raw)