---
title: "Provision"
method: POST
path: "/v1/numbers"
tags: ["Numbers"]
---

# Provision

`POST /v1/numbers`

## Request

- Base URL: `https://api.agentline.cloud`
- URL: `https://api.agentline.cloud/v1/numbers`
- Auth: HTTP bearer

Buy a US or Canadian phone number for your AI agent.

Buys a real +1 number from the carrier, attaches it to the agent and
uses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make
outbound calls and answers inbound calls on this number. Existing numbers retain their carrier.
Each agent can have only one active number.

Prerequisites: an agent from create_agent with no active number (each
agent has at most one; a second purchase returns HTTP 409), plus a remaining
subscription number allowance or $3.00 in the wallet
(HTTP 402 otherwise; see get_account_balance).

Returns the number's id (num_..., used by release_phone_number and as
from_number_id), phone_number, country, number_type, status, cost,
balance_remaining and a private number card link (card_url,
card_image_url, card_url_expires_at). If the account has an owner email,
the card link is also emailed there.

## Request body

- NumberProvision
  - `agent_id` string, required: ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')
  - `country` string: Country code for the phone number ('US' or 'CA')
  - `number_type` string: 'local' for a number in a geographic area code, or 'tollfree' for a toll-free 8xx number
  - `area_code` string, nullable: For local numbers, the area code the number should be in, written as 3 digits (US e.g. '212' NYC, '415' SF; Canada e.g. '416' Toronto, '604' Vancouver, '514' Montreal); other values make the purchase fail. For tollfree, a prefix such as '800' or '888' narrows the search and other values are ignored. Omit to take any available number.
  - `pattern` string, nullable: Legacy search: digits the local number must contain, e.g. '555'. Used only for local numbers when area_code is omitted; prefer area_code.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents.md) · [All operations](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/revisions/18c0bdbb4b30?raw)