Hail

The 38 tools it listed

"Read only" and "Changes data" are the server's own marks. Underlined parameters are required.

1. acquire_numberChanges data

   Buy a phone number

   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. ``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. ``verification_id`` picks which approved ver

   quote_id country_code number_type confirm_total_cents idempotency_key subject_type verification_id

2. cancel_verificationChanges data

   Cancel a verification

   Cancel a verification that has not been sent for review, or dismiss a rejected one (needed before submitting a new one for the same country and number type). The draft is discarded. Works in state ``awaiting_review`` or ``rejected``, and for an ``approved`` US SMS registration (``purpose: "sms"``): its numbers leave the campaign, US-to-US texts from them fail again, and its monthly fee stops after the current month. Some registrations bill at least 3 monthly fees from approval, so cancelling sooner can still charge 3 months. Ask the user first. A ``submitting`` or ``submitted`` verification is under review and cannot be cancelled (409): wait for the result with get_verification. Returns the verification with ``state: "cancelled"``, or ``{"error": "<message>"}``.

   verification_id

3. confirm_verification

   Confirm a verification with a code

   When a registration shows confirmation 'code', ask the person for the code the carrier texted and submit it here. ``verification_id`` comes from submit_verification or list_verifications. ``code`` is 4 to 10 characters. A wrong or expired code is an error naming ``code``; the carrier sends a new one after a day. On success the registration moves on; poll get_verification until ``approved``. A ``confirmation`` of ``reply`` means the person answers the carrier's text instead; nothing is entered here. Returns the verification or ``{"error": "<message>"}``.

   verification_id code

4. create_agent

   Create an agent

   Save an agent. Then call ``route_number`` so a number answers with it, or pass its id as ``agent_id`` to ``place_call``. ``system_prompt`` is what the agent follows. ``first_message`` is spoken after the AI line; omit it to let the caller speak first. ``ai_disclosure_line`` replaces the workspace AI line for this agent; ``{org}`` becomes the organization name. ``language`` is a lowercase ISO 639-1 code. ``max_duration_seconds`` is 60..3600. ``handover_max_duration_seconds`` (60..3600, default 1800) is the call limit once a handover contact answers. ``handover_contacts``: People the agent may hand a live call to: ``[{contact_id, note}]`` (max 10; ``note`` 1-200 chars says when to hand over). ``contact_id`` is an id from ``list_contacts``: a contact's uuid, or ``member:<user id>`` for a team member. The person needs a phone number. The agent never sees it. Returns the API's `

   name system_prompt first_message ai_disclosure recording_enabled ai_disclosure_line language voice_id tools max_duration_seconds handover_max_duration_seconds voice_enabled sms_enabled handover_contacts

5. create_contact

   Create a contact

   Save a new contact for the workspace. Provide at least one of ``phone_e164`` (E.164, e.g. ``+14155551234``) or ``email`` — the API rejects (422) a contact with neither. A duplicate phone or email on an existing contact returns 409. Example: create_contact(name="Maya Chen", phone_e164="+14155551234") Returns the created contact entry as a dict. On failure returns ``{"error": "<message>"}`` instead.

   name phone_e164 email

6. delete_agentChanges data

   Delete an agent

   Delete a saved agent. DESTRUCTIVE. Ask the user before calling this. Numbers that used the agent stop answering with it: calls ring out and texts reach webhooks only. Reroute them first with ``route_number`` if that matters. ``confirm_name`` must equal the agent's ``name``. The tool reads the agent first and refuses with ``{"error": ...}`` on a mismatch, without deleting anything. To stop an agent without deleting it, use ``update_agent`` with ``status="paused"``. Returns ``{"deleted": true, "agent_id", "name"}``, or ``{"error": "<message>"}``.

   agent_id confirm_name

7. get_agentRead only

   Get an agent

   Fetch one saved agent by id. ``agent_id`` comes from ``list_agents`` or ``create_agent``. Returns the ``AgentResponse`` as a dict (``name``, ``system_prompt``, ``first_message``, ``ai_disclosure``, ``voice_config``, ``tools``, ``voice_enabled``, ``sms_enabled``, ``status``, ...), or ``{"error": "<message>"}``.

   agent_id

8. get_callRead only

   Get a call

   Fetch the current state of one call by id. Use this after ``place_call`` (or to check on any prior call) to read the call's latest ``status`` and timing fields. Returns the API's ``CallResponse`` as a dict, or ``{"error": "call not found"}`` for an unknown id.

   call_id

9. get_emailRead only

   Get an email

   Fetch the full record of one email by id. Returns the complete row — including ``body_text`` / ``body_html`` and (for inbound mail) the ``in_reply_to`` / ``message_id`` headers and ``spam``/``virus``/``spf``/``dkim``/``dmarc`` verdicts. Use this after ``list_emails`` to read a received reply's body. Returns the API's ``EmailResponse`` as a dict, or ``{"error": "resource not found"}`` for an unknown id.

   email_id

10. get_email_attachmentRead only

    Get an email attachment

    Get a fetchable URL for one inbound email attachment. ``attachment_id`` comes from an item in ``get_email``'s ``attachments`` list. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the attachment bytes, fetchable directly with no auth header. Unknown ids return ``{"error": "resource not found"}``.

    email_id attachment_id

11. get_email_eventsRead only

    Get email events

    Delivery/engagement timeline (sent→delivered→opened…) for one email. Chronological lifecycle events for a single email — use this to see exactly what happened to one message (bounced? opened? clicked?) rather than the account-wide aggregates ``get_email_stats`` returns. Returns ``{"items": [...], "next_cursor": ...}`` where each item has ``kind`` (one of sent, delivered, delivery_delayed, bounced, complained, rejected, opened, clicked), ``payload``, and ``occurred_at``. ``opened`` and ``clicked`` only occur for emails sent with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. Pass ``cursor`` from a previous ``next_cursor`` to page (``limit`` 1..1000, default 100). On failure returns ``{"error": "resource not found"}`` for an unknown id.

    email_id cursor limit

12. get_email_rawRead only

    Get raw email

    Get a fetchable URL for an email's original MIME source. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the full raw RFC822 message. Fetch the URL directly to read the complete original; it needs no auth header. Raw source exists for **inbound** mail only — outbound ids return ``{"error": "resource not found"}``.

    email_id

13. get_email_statsRead only

    Get email stats

    Account-level email deliverability stats (counts, rates, time series). Aggregates across your whole organization's outbound mail over a window — use this for "how's deliverability doing" rather than one message's history (``get_email_events`` covers that). ``from_`` / ``to`` are ISO 8601 timestamps (defaults: last 7 days ending now). ``bucket`` is ``"day"`` (default) or ``"hour"`` — ``"hour"`` is limited to an 8-day span; any range is capped at 92 days. Returns ``{"from": ..., "to": ..., "bucket": ..., "totals": {...}, "rates": {...}, "series": [...]}`` — ``totals``/each ``series`` bucket carry counts (sent, delivered, bounced, opened, ...) and ``rates`` carries derived ratios (delivery, bounce, open, click), each ``None`` when ``totals.sent`` is 0. Open and click numbers only count HTML emails. Plain-text-only emails are never tracked for opens or clicks, so they lower th

    from_ to bucket

14. get_eventsRead only

    Get events

    Page through events from across the org or one resource. Pass ``id="<type>:<uuid>"`` to narrow to a single resource — supported types are ``call``, ``email``, and ``sms`` (e.g. ``id="sms:<uuid>"`` after ``send_sms``). When narrowed to a call, the response includes a ``call_status`` field reflecting the call's current state. Without ``id``, returns events from across the whole org. ``kind`` filters server-side by event kind (``state_change``, ``agent_turn``, ``user_turn``, ``tool_call``, ``error``, ...). This is **not** a streaming subscription — the call returns whatever events exist now plus a ``next_cursor`` if more pages remain. To follow a call to completion, loop: pass the previous response's ``next_cursor`` until ``next_cursor`` is null and, when narrowed to a call, ``call_status`` is one of ``completed``, ``failed``, ``busy``, ``no_answer``, ``canceled`` (the

    id kind cursor limit

15. get_numberRead only

    Get a number

    Fetch one dedicated number by id: its state, capabilities and which agents answer its calls and texts. ``number_id`` comes from ``list_numbers``. Returns the ``PhoneNumberResponse`` as a dict, or ``{"error": "<message>"}``.

    number_id

16. get_smsRead only

    Get a text message

    Fetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...")

    sms_id

17. get_verificationRead only

    Get a verification

    Fetch one verification and its state. Use it to poll. There is no notification, and review takes business days. Poll every few minutes to hours, not every few seconds; the state refreshes from the carrier at most once a minute. On ``approved``: call quote_numbers again. The offer is now ``ready``; then acquire_number. On ``rejected``: read ``rejection_reason``, ask the user, dismiss it with cancel_verification, then submit a new one. ``verification_id`` comes from submit_verification or list_verifications. Returns ``{"id", "state", "rejection_reason", ...}`` or ``{"error": "<message>"}``.

    verification_id

18. get_verification_requirementsRead only

    Get verification requirements

    Read what the carrier needs to verify the organization before it can buy a number. Call this when quote_numbers shows an offer with ``readiness == "verification_required"``. Read-only. ``country_code`` is ISO alpha-2 (for example ``"GB"``). ``number_type`` is ``local``, ``mobile``, ``national`` or ``toll_free``. ``subject_type`` is required: ``person`` (the user) or ``business`` (the user's company). Never guess it: ask the user "you or your company?". The result's ``subject_types`` lists what the carrier accepts. The organization may hold one verification of each. ``quote_id`` is the offer's ``quote_id`` from quote_numbers. It is required for ``purpose='number'``: the form is the one for that offer. ``purpose`` is ``number`` (default, to buy a number) or ``sms``. ``purpose='sms'`` registers the organization to text US numbers from a US number (country_code US, number_type local).

    country_code number_type subject_type quote_id number_id purpose

19. list_agentsRead only

    List agents

    List the workspace's saved agents: the brains that answer calls and texts on its numbers, and that ``place_call`` can use via ``agent_id``. Returns ``{"items": [{"id", "name", "system_prompt", "first_message", "ai_disclosure", "ai_disclosure_line", "voice_config", "tools", "max_duration_seconds", "handover_max_duration_seconds", "voice_enabled", "sms_enabled", "status", "handover_contacts"}, ...]}``.

20. list_callsRead only

    List calls

    List recent calls in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. ``status`` (one of queued, dialing, ringing, in_progress, completed, failed, busy, no_answer, canceled) and ``to`` (E.164) are optional server-side filters. Returns a dict ``{"items": [...], "next_cursor": <str|None>}``.

    cursor limit status to

21. list_contactsRead only

    List contacts

    List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use ``lookup_contact`` for name searches. ``q`` optionally filters server-side (matches name/email/phone). ``limit`` caps the page (server default 100, max 500). Returns ``{"items": [{"id", "kind", "name", "phone_e164", "email", "role"}, ...]}`` — ``kind`` is ``"member"`` (id ``member:<user_id>``, ``role`` set) or ``"manual"`` (id is the contact's UUID, ``role`` null).

    q limit

22. list_email_domainsRead only

    List email domains

    List the addresses this workspace can send email from. Call this BEFORE ``send_email`` when you do not already know the ``from_`` address — do not guess a domain. Returns ``{"items": [...], "next_cursor": ..., "default_from": ...}``. Each item carries ``domain``, ``kind`` (``"custom"`` or ``"hail_mail"``) and ``verification_status``; only ``"verified"`` rows can send. A ``custom`` item's ``domain`` is a bare DNS name that accepts any local-part (``[email protected]``); a ``hail_mail`` item's ``domain`` is already a full address. ``default_from`` is the address a ``send_email`` with no ``from_`` goes out as. A verified custom domain wins over the hail-mail address. It is null when the workspace has several verified custom domains — then ``send_email`` rejects a missing ``from_`` and you must pass one from ``items``. Example: list_email_domains()

    cursor limit

23. list_emailsRead only

    List emails

    List emails in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. Two optional server-side filters: * ``direction`` — ``outbound`` or ``inbound``. Pass ``direction="inbound"`` to read replies and other received mail. * ``status`` — one of ``queued``, ``sent``, ``failed``, ``bounced``, ``complained``, ``received``. Items are trimmed summaries (no message body). Call ``get_email`` with an item's ``id`` to read the full body. Example: list_emails(direction="inbound") Returns ``{"items": [...], "next_cursor": <str|None>}`` on success, or ``{"error": "<message>"}`` instead.

    cursor limit status direction

24. list_number_regionsRead only

    List number search regions

    List the US state and Canadian province codes that quote_numbers accepts as ``region`` (optional, with ``city``). Returns ``{"regions": [{"country_code", "code", "name"}]}``, such as ``{"country_code": "US", "code": "AZ", "name": "Arizona"}``, or ``{"error": "<message>"}``.

25. list_numbersRead only

    List numbers

    List the workspace's dedicated phone numbers, newest first. ``limit`` is 1..200 (default 50). Pass the returned ``next_cursor`` as ``cursor`` for the next page. Returns ``{"items": [{"id", "e164", "country_code", "number_type", "capabilities", "provisioning_state", "voice_agent_id", "sms_agent_id", ...}], "next_cursor"}``, or ``{"error": "<message>"}``.

    limit cursor

26. list_smsRead only

    List text messages

    Page through recent SMS messages for your organization. ``status`` filters to one of: queued, sent, delivered, failed, undelivered, received. ``to`` filters to messages sent to a specific E.164 number. Paginate with the returned ``next_cursor``.

    cursor limit status to

27. list_verificationsRead only

    List verifications

    List the organization's carrier verifications, newest first. ``purpose`` is ``number`` or ``sms``; only that kind is listed. Omit to see every registration. ``purpose='sms'`` lists the registrations to text US numbers from a US number. Returns ``{"items": [{"id", "country_code", "number_type", "subject_type", "subject_name", "purpose", "state", "rejection_reason", "created_at", "updated_at", "submitted_at", "approved_at", "confirmation", "step", "identity_confirmed"}]}``. ``step`` says where a US texting filing in progress is: ``confirm_identity``, ``filing`` or ``carrier_review``. ``identity_confirmed`` on a person's newest filing, when cancelled or rejected: the next one with the same person needs no code. Dismiss a rejected filing first. ``state`` is ``awaiting_review``, ``submitting``, ``submitted``, ``approved``, ``rejected`` or ``cancelled``. Use it to check whether a

    purpose

28. lookup_contactRead only

    Look up a contact

    Find a contact by name, email, or phone fragment. Resolve a person to their ``phone_e164``/``email`` BEFORE calling ``place_call``, ``send_sms``, or ``send_email`` — do not guess a contact's number. Returns up to 10 matches, same item shape as ``list_contacts``. Example: lookup_contact(query="maya")

    query

29. place_call

    Place a phone call

    Originate an outbound phone call. Provide ``system_prompt`` (mode A — Hail's bundled fallback LLM uses this prompt) or ``llm`` (mode B — bring your own OpenAI-compatible endpoint as ``{"base_url": ..., "api_key": ..., "model": ...}``), or both, or ``agent_id`` (a saved agent from ``list_agents`` supplies the prompt, first message, AI line, voice and tools; fields you pass here win). At least one is required. Passing both runs your prompt on your own endpoint: it receives Hail's voice preamble plus your prompt as the leading system message. ``to`` must be E.164 (e.g. ``+14155551234``). ``from_`` is optional and defaults to the first active number on your org. ``first_message`` is spoken verbatim on pickup; omit it to let the agent open the conversation itself — it reacts to how the call was answered, or introduces itself after silence. ``language`` sets the call's sp

    to recipient_consent system_prompt llm from_ first_message language ai_disclosure recording_enabled metadata tools idempotency_key consent_source consent_obtained_at message_type agent_id

30. quote_numbersRead only

    Quote phone numbers

    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``,

    country_code capabilities number_type area_code city region

31. release_numberChanges data

    Release a number

    Release a phone number. DESTRUCTIVE and permanent. Calls and texts to the number stop. This month's fee and any earlier months are still billed. There is no refund. The number may not be recoverable. Ask the user before calling this. ``confirm_e164`` must equal the number's ``e164`` (for example ``"+14155550100"``). The tool reads the number first and refuses with ``{"error": ...}`` on a mismatch, without releasing anything. A number whose order is still pending cannot be released (409). A number whose order failed was never bought: the call only hides it from the list and returns ``{"dismissed": true, "number_id", "e164"}``. Returns ``{"released": true, "number_id", "e164"}``, or ``{"error": "<message>"}``.

    number_id confirm_e164

32. route_number

    Route a number to an agent

    Choose which agent answers a number's calls and texts. ``voice_agent_id`` makes the number answer calls with that agent (Hail registers it for inbound at the carrier and LiveKit); ``clear_voice=True`` stops answering calls. ``sms_agent_id`` makes the agent reply to texts; ``clear_sms=True`` stops that. A field left out keeps its value. ``number_id`` comes from GET /numbers. Returns the updated ``PhoneNumberResponse`` as a dict, or ``{"error": "<message>"}``.

    number_id voice_agent_id sms_agent_id clear_voice clear_sms

33. send_email

    Send an email

    Send an outbound email through your configured SES sender. ``to`` is a non-empty list of RFC-style email addresses. At least one of ``body_text`` / ``body_html`` is required (both is fine — multipart-alternative). Prefer including ``body_html``: open and click tracking only works for emails with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. ``cc``, ``bcc``, and ``reply_to`` are optional and follow the usual mail conventions. Hail sets no ``reply_to`` of its own — to have replies reach the human running this session, call ``whoami`` and pass their ``email``. ``recipient_consent`` is required and must be the JSON boolean ``true`` (strings and numbers are refused): attest that you (the caller triggering this request) have obtained the lawful consent needed to email this recipient. The API re

    to subject recipient_consent body_text body_html from_ from_name cc bcc reply_to metadata idempotency_key consent_source consent_obtained_at message_type attachment_ids

34. send_sms

    Send a text message

    Send an outbound SMS. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. With no ``from_``: destinations where the sender-ID carrier delivers a dynamic alphanumeric sender ID unchanged (about 110 countries, see core/hailhq/core/sender_id_corridors.py) use your organization's sender ID (or ``HAIL``, the platform default); Australia (+61) may use ``HAIL`` instead; every other destination, including the US and Canada, uses your organization's oldest active SMS-capable number and the API returns 422 when there is none. SMS never uses the shared voice-call pool. ``recipient_consent`` is required and must be the JSON boolean ``true`` (strings and numbers are refused): attest that you (the caller triggering this request) have obtained the lawful consent needed to text this recipient. The API rejects the request (422) if this is not ``true``

    to body recipient_consent from_ metadata idempotency_key consent_source consent_obtained_at message_type

35. submit_verificationChanges data

    Submit a verification

    Send the user's personal or company details and identity documents to the carrier for verification. IRREVERSIBLE: once submitted it cannot be cancelled, and the carrier keeps the documents. ``attest_authorized``: pass true only if the person or company named in these details and documents asked for this submission and gave you the details and files in this conversation. Never invent, guess, infer or reuse personal data or documents. Anything else: pass false (the call then sends nothing). ``purpose`` is ``number`` (default) or ``sms``. ``purpose='sms'`` registers the organization to text US numbers from a US number (country_code US, number_type local). The carrier fee is debited from credit at filing. Pass the same ``purpose`` to get_verification_requirements. For ``purpose='number'``, pass the same ``quote_id`` you passed to get_verification_requirements. For ``purpose='sm

    country_code number_type fields documents files attest_authorized subject_type address quote_id number_id purpose

36. update_agent

    Update an agent

    Change a saved agent. Safe to repeat: the same call gives the same result. Only the fields you pass change; a field left out keeps its value. ``status`` is ``"live"`` or ``"paused"``; a paused agent does not answer. ``language`` is a lowercase ISO 639-1 code. Pass ``language`` or ``voice_id`` alone: the other value is kept. ``max_duration_seconds`` and ``handover_max_duration_seconds`` are 60..3600. ``handover_contacts`` replaces the whole list: ``[{contact_id, note}]`` (max 10) as in ``create_agent``; ``[]`` removes every contact. To remove a value, list its name in ``clear_fields``. Allowed: ``first_message`` (the agent waits for the caller), ``ai_disclosure_line`` (back to the workspace line), ``tools`` (back to all tools), ``max_duration_seconds`` (back to the workspace limit), ``handover_max_duration_seconds`` (back to 1800). Any other name is refused. Do not set and c

    agent_id name system_prompt first_message ai_disclosure recording_enabled ai_disclosure_line language voice_id tools max_duration_seconds handover_max_duration_seconds voice_enabled sms_enabled status handover_contacts clear_fields

37. upload_email_attachment

    Upload an email attachment

    Upload a file to attach to a future outbound email. ``content_base64`` is the file's raw bytes, base64-encoded. Returns ``{"id": ..., "filename": ..., "content_type": ..., "size_bytes": ...}`` — pass ``id`` in ``send_email``'s ``attachment_ids`` list. The id is reusable across many sends and expires in 24h if never used. Files over 25MB (combined with the message body and any other attachments, per send) are rejected — host large files externally and link to them in the body instead.

    content_base64 filename content_type

38. whoamiRead only

    Who am I

    Identify the human whose credentials this session runs under. Use it to sign or route mail as that person: pass their address as ``send_email(reply_to=...)`` so replies reach them rather than the sending domain, which is often an unattended ``noreply@``. Returns ``{"auth_kind", "organization_id", "user_id", "email", "name"}``. ``user_id``/``email``/``name`` are null when the server runs on a shared operator key (``auth_kind="shared"``) — there is no human behind it, so send without a ``reply_to``. Example: whoami()