Numbers

Provision

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.

post/v1/numbers

Request

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

Request body

agent_idstring required

ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')

countrystring

Country code for the phone number ('US' or 'CA')

number_typestring

'local' for a number in a geographic area code, or 'tollfree' for a toll-free 8xx number

area_codestring 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.

patternstring 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

Successful Response

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.