Buy a phone number
acquire_numberBuy a quoted phone number with explicit price confirmation.
This charges the setup fee and first month immediately, then renews monthly.
The purchase requires the user's authorization for that number and cost.
Expired or changed offers return 409 without authorizing a different price.
Each quote can buy at most one number.
A retry with the same quote and ``idempotency_key`` refers to the original purchase.
After a timeout, a new quote starts a different purchase and can buy a second number.
A returned retry key is available after a timeout or server error.
A 4xx failure returns no retry key; that failed request cannot be reused.
A rejected or ambiguous registration selection returns 422.
A purchase does not assign an answering agent automatically.
Returns the number record and ``idempotency_key``, or an error with any available retry key.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"quote_id": "<quote_id>",
"country_code": "<country_code>",
"number_type": "<number_type>",
"confirm_total_cents": "<confirm_total_cents>"
},
"name": "acquire_number"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| quote_id | Yes | ``quote_id`` of one offer from ``quote_numbers``. | |
| llm_model | No | Model ID of the calling agent. Optional. Recorded for analytics only. | |
| number_type | Yes | Kind of number being bought: copy the offer's ``number_type`` from ``quote_numbers``. Hail checks it against the offer. | |
| country_code | Yes | Country of the number being bought, as an ISO alpha-2 code: the ``country_code`` sent to ``quote_numbers`` for this offer. | |
| subject_type | No | Whose approved registration may be used: the user's own (``person``) or their company's (``business``). Omitted: either. | |
| idempotency_key | No | Retry key. The ``idempotency_key`` from an earlier response refers to that original request instead of starting a new one. Omitted: a new key is generated and returned. | |
| verification_id | No | Which approved registration covers this purchase: an ``id`` from the offer's ``verifications``. Give it when the offer lists more than one approved registration. Omitted: the only approved one, if any. | |
| confirm_total_cents | Yes | The offer's ``setup_cents`` plus ``monthly_cents``, in USD cents, as the user authorized it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||