acquire_number

io.github.hail-hq/hail-mcp · Verify this server

Buys a real phone number. It charges the setup fee and the first month now and renews monthly. Call quote_numbers first. Pass the offer's quote_id, country_code, number_type, and confirm_total_cents = monthly_cents + setup_cents from that offer. If the quote expired or the price changed (409) you get an error: quote again. Only buy when your user asked for this number. After buying, call route_number to point it at an agent. A quote buys at most one number. After a timeout, retry with the same quote_id and idempotency_key, or check list_numbers. Never request a new quote after a timeout. ``provider`` is ``auto`` (the quoted carrier) or the quoted carrier's name. ``idempotency_key`` is optional; to retry after a timeout or a 5xx, pass the ``idempotency_key`` that result returned, so the number is bought once. A 4xx error returns no key: the API remembers that failure under it, so drop it and quote again. Returns the number (``id``, ``e164``, ``provisioning_state``, ...) plus ``idempotency_key``, or ``{"error": "<message>", "idempotency_key": ...}``.