Quote phone numbers
quote_numbersRead-onlyIdempotent
Compare live phone-number offers from carriers by country, capabilities, number type, and location to find a ready-to-buy number.
Instructions
Compare live phone-number offers from the carriers. Read-only: it buys nothing and charges nothing.
``country_code`` is an ISO alpha-2 code such as ``"US"``.
``capabilities`` is ``["voice"]``, ``["sms"]`` or both (default).
``number_type`` is ``local``, ``mobile``, ``national`` or
``toll_free``; omit it to compare all types.
``area_code`` is an area code or the first digits of the number, as
dialed in the country: ``"020"`` (London), ``"480"`` (Arizona).
``city`` is a city name such as ``"London"``. Each offer has
``locality`` and ``region`` (such as ``"Phoenix"``, ``"AZ"``): check
them, since city names repeat across states. ``region`` (optional,
with ``city``) is a US/CA state code; list_number_regions lists them.
Omit all three to search the whole country.
Returns ``{"offers": [...], "recommended_quote_id", "expires_at"}``.
Each offer has ``e164``, ``number_type``,
``capabilities``, ``monthly_cents``, ``setup_cents``, ``readiness``,
``requirements``, ``subject_types``, ``verifications`` and
``quote_id``. Money fields are cents (USD).
Quotes expire in 10 minutes (``expires_at``); quote again after that.
``subject_types`` says who may verify for the number: ``person``
(the user), ``business`` (the user's company), or both; empty when no
verification is needed. ``verifications`` lists the verifications
the offer can be bought with (``id``, ``state``, ``subject_type``,
``subject_name``), approved first: those of an accepted subject type
still under review, and the approved ones the carrier still accepts
for the offer. ``subject_name`` is the person's or company's name from the
verification form. When several are approved, show the user the
names and ask which one buys the number; pass its ``id`` as
``verification_id`` to acquire_number.
An offer with ``readiness == "verification_required"`` cannot be
bought until the organization is verified. Ask the user "you or your
company?" to pick the ``subject_type`` (one of ``subject_types``).
Call get_verification_requirements, ask the user for the details,
then submit_verification, both with the offer's ``quote_id`` and that
``subject_type``, and poll get_verification (review takes business
days). ``requirements``
lists what the carrier needs. Prefer an offer whose
``readiness`` is ``"ready"``; ``recommended_quote_id`` points at the
best one, or is null if none is ready.
An offer with ``by_request: true`` has no ``e164``: support orders
that number by hand. acquire_number refuses it; tell the user to ask
support. Its ``quote_id`` still works for verification.
Errors come back as ``{"error": "<message>"}``.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| region | No | ||
| area_code | No | ||
| number_type | No | ||
| capabilities | No | ||
| country_code | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||