buy_number
ActiveTool of KaiCalls
Purchase a real phone number from the carrier and register it to a business. This spends real money — the number is billed by the carrier immediately, so the purchase is APPROVAL-GATED: without human-grade authority (an authority envelope with mode human_confirmed, or a dashboard approval) the tool executes nothing and returns a pending_approval record the business owner approves or denies from the dashboard — relay the returned confirmation text to them. Agent-initiated purchases never run unattended. Does not auto-attach an agent; call attach_number afterward to route it. Mirrors POST /api/v1/phone-numbers/purchase via the numbers.purchase update intent. Compliance: KaiCalls automatically applies state-aware AI-disclosure and consent handling to numbers it provisions, and flags high-risk business categories for extra review.
Parameters schema
{
"type": "object",
"required": [
"phone_number"
],
"properties": {
"actor": {
"type": "object",
"description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
},
"reason": {
"type": "string",
"description": "Optional reason recorded in the durable audit."
},
"dry_run": {
"type": "boolean",
"description": "Validate tenant, scope, and policy without buying anything."
},
"agent_id": {
"type": "string",
"description": "Agent ID to route this number to directly once purchased (optional; requires the number to also be voice-runtime-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call)."
},
"authority": {
"type": "object",
"description": "How the purchase was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval."
},
"source_ref": {
"type": "string",
"description": "External source reference, such as a ticket or automation run ID."
},
"business_id": {
"type": "string",
"description": "Business ID (optional only when the token can access exactly one business)."
},
"phone_number": {
"type": "string",
"description": "The exact E.164 phone number to purchase, as returned by search_available_numbers."
},
"idempotency_key": {
"type": "string",
"description": "Stable key for the purchase request; repeating it returns the original outcome. Defaults to a key derived from the phone number — pass your own to retry a previously failed purchase."
},
"queue_for_approval": {
"type": "boolean",
"description": "When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms."
}
}
}No endpoints wrapped at confidence ≥ 0.50.
Parent server
KaiCalls
https://github.com/cgallic/kai_calls
1/7 registries