Hail

Buy 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. ``quote_id``, ``country_code`` and ``number_type`` identify a current offer. ``confirm_total_cents`` must equal the offer's setup fee plus monthly fee. 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. ``verification_id`` selects an approved registration accepted by the offer. It is required when several approved registrations are eligible. ``subject_type`` optionally limits eligible registrations to ``person`` or ``business``. 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.

Correct an existing SMS registration at the needs_information step. ``verification_id`` identifies the same paid application and identity. ``fields`` contains complete corrected answers that satisfy the current requirements. The address must be accurate; saved details can be reused when still correct. Identity changes are rejected. This operation does not create a replacement brand. ``attest_authorized=true`` attests that the applicant reviewed and authorized the corrections. Actual consent evidence is required. Limits are 100 fields and 64 KiB of combined fields and address. No documents are uploaded. A later campaign filing can incur the normal review fee. After a timeout, the existing registration can already reflect the correction. Returns the updated registration or an error.

Cancel an eligible carrier registration after explicit user authorization. Awaiting-review drafts are discarded; rejected registrations are dismissed. A rejected registration must be dismissed before a new one is submitted for the same country and number type. An approved US SMS registration can be cancelled: attached numbers lose US texting eligibility and its monthly fee ends after the current month. Some registrations have a minimum of three monthly fees even after early cancellation. Submitting or submitted registrations normally return 409; an accepted SMS campaign at runtime_setup is an exception. An SMS application at needs_information supports correction on its existing paid identity. Returns the cancelled registration or an error.

Check a carrier registration form without filing anything. Takes the same arguments as ``submit_verification`` except ``attest_authorized``. Runs every check Hail can run before filing: purpose rules, credit (402), the carrier's current form, duplicates (409), field lengths, each file (type, size, and for ``upload_id`` that it is this workspace's verification document, uploaded within the last hour), and the form's required fields, documents and address (for ``purpose="sms"``, the US texting application). Nothing is filed, saved, held or charged, and uploads stay usable. Returns ``ok``, ``files`` (slot, upload_id, size_bytes, sha256 per file) and ``note``; problems come back as ``problems`` with the field named. The carrier runs its own checks at submission.

Confirm a registration using the code the carrier sent to the applicant. ``verification_id`` identifies a registration with ``confirmation="code"``. ``code`` is the applicant-supplied code, containing 4 to 10 characters. Incorrect or expired codes return a field error; the carrier can send a replacement after a day. Success advances the registration but does not guarantee immediate approval. A ``confirmation="reply"`` registration requires a direct reply to the carrier's text instead. Returns the updated registration or an error.

Save an agent for phone calls and text replies. ``system_prompt`` defines the saved agent's behavior. ``first_message`` is an optional greeting after the AI disclosure. Without a greeting, an inbound agent waits for the caller. ``ai_disclosure_line`` overrides the workspace line; ``{org}`` expands to the organization name. ``language`` is a lowercase ISO 639-1 code. ``max_duration_seconds`` is 60 to 3600. ``handover_max_duration_seconds`` is 60 to 3600, defaulting to 1800. ``handover_contacts`` contains up to ten ``{contact_id, note}`` entries. Contact IDs are UUIDs or ``member:<user_id>``. Each contact needs a phone number. Each note is 1 to 200 characters. The phone number is hidden from the call agent. Saving an agent does not change any phone number's routing. Returns the saved agent record or an error.

Save a workspace contact with a name and a phone number or email address. At least one of ``phone_e164`` or ``email`` is required. Phone numbers use E.164 format. A duplicate phone or email returns 409. Returns the new contact record or an error.

Create a one-time link that uploads one file from a shell with curl. The bytes go from the local disk to Hail directly, not through the tool call, so any file that is not tiny goes this way. ``purpose`` is ``email_attachment`` (25 MB at most; the ``id`` works in ``send_email``'s ``attachment_ids``) or ``verification_document`` (JPG, PNG or PDF, 10 MB at most; ``{"slot": ..., "upload_id": id}`` works in the ``files`` of ``check_verification`` and ``submit_verification`` for 1 hour after the upload). ``content_type`` is the file's MIME type, like ``application/pdf``. Returns ``id``, ``upload_url``, ``expires_at`` (15 minutes), ``max_bytes`` and a ready ``curl`` line with a placeholder for the file's path after ``@``. The link needs no key and works once. The upload response holds ``size_bytes`` and ``sha256`` to compare with the local file.

Permanently delete a saved agent after explicit user authorization. ``confirm_name`` must match the agent's saved name. A mismatch returns an error without deleting anything. Numbers assigned to the deleted agent stop answering calls with it; texts are delivered to webhooks only. Pausing an agent is a separate non-deleting status change. Returns ``deleted``, ``agent_id`` and ``name``, or an error.

Read one saved workspace agent by ID. Returns its name, instructions, greeting, disclosure, voice settings, enabled channels, status, limits and other saved settings, or an error.

Read a call's current status and timing by ID. ``call_id`` identifies an existing workspace call. Returns the call record, or an error when the call is unavailable.

Read a complete workspace email by ID. Returns ``body_text``, ``body_html`` and other email fields. Inbound records include reply headers and spam, virus, SPF, DKIM and DMARC verdicts. Attachments include IDs and file metadata. An unknown or inaccessible email returns an error.

Return a temporary download URL for an inbound email attachment. ``email_id`` identifies the email; ``attachment_id`` identifies one of its attachments. The URL expires after approximately five minutes and requires no authorization header. Returns ``url``, or an error for an unavailable attachment.

Read one email's delivery and engagement timeline. Events include sent, delivered, delivery_delayed, bounced, complained, rejected, opened and clicked, with ``payload`` and ``occurred_at``. Open and click events require an HTML email body. ``cursor`` accepts the previous page's ``next_cursor``. ``limit`` is 1 to 1000; the default is 100. Returns ``items`` and ``next_cursor``, or an error.

Return a temporary download URL for an inbound email's original MIME source. The URL expires after approximately five minutes and requires no authorization header. Raw source is available only for inbound emails. Returns ``url``, or an error for an unavailable email.

Read workspace email delivery counts, rates and time series. ``from_`` and ``to`` are ISO 8601 timestamps, defaulting to the last seven days. ``bucket`` is ``day`` or ``hour``. Hourly ranges are limited to eight days. All ranges are limited to 92 days. Returns ``from``, ``to``, ``bucket``, ``totals``, ``rates`` and ``series``. Rates are null when the sent count is zero. Open and click counts cover HTML emails only; plain-text emails lower these rates. An upstream failure returns an error.

Read a page of workspace events or events for one resource. ``id`` optionally selects ``call:<uuid>``, ``email:<uuid>`` or ``sms:<uuid>``. ``kind`` filters event types such as state_change, agent_turn, user_turn, tool_call or error. ``cursor`` accepts the previous page's ``next_cursor``. A call-specific response includes the current ``call_status``. Terminal call states are completed, failed, busy, no_answer and canceled. The response is a snapshot, not a streaming subscription. Returns ``items``, ``next_cursor`` and optional ``call_status``, or an error.

Read a workspace number's state, capabilities and assigned agents. ``number_id`` identifies the number. Returns the number record or an error.

Read a text message's current state by ID. ``sms_id`` identifies an existing workspace message. Returns the message record, including delivery status, or an error.

Read saved answers for an existing workspace SMS registration. Returns private applicant fields, address and available sender information. ``verification_id`` identifies the original application, including one needing corrections. An older application without saved answers returns 404. This read can recover an existing sender's details but creates no brand and files no campaign. Corrections retain the existing registration and its paid identity.

Read one carrier registration's current state and reported next step. ``verification_id`` identifies an existing registration. The carrier state refreshes at most once per minute. Review can take business days. ``step="needs_information"`` means the existing SMS application needs corrections; its saved applicant details and paid identity remain attached to the same registration. An approved registration can make matching number offers ready for purchase. Rejections include ``rejection_reason``. ``waiting_for_credit`` indicates a fee awaiting payment. ``credit_needed_cents`` is this registration's share of the additional credit needed. Returns the registration record or an error.

Read a carrier's current registration fields, documents, address rules and fees. ``purpose`` is ``number`` or ``sms``. ``number`` is the default. ``country_code`` is an ISO alpha-2 code. ``number_type`` is local, mobile, national or toll_free. ``subject_type`` identifies the actual applicant: ``person`` or ``business``. The response's ``subject_types`` identifies the types the carrier accepts. For number registration, ``quote_id`` is required and selects the exact offer's form. US SMS registration uses ``purpose="sms"``, country ``US`` and type ``local``. ``number_id`` identifies an existing workspace US number when required by the carrier. Applicant country and business tax status determine the registration route. The personal route is available to US or Canadian applicants without a business tax number. SMS fees apply at submission, carrier review and monthly after approval. Returns ``required``, ``fields``, ``documents`` and ``address_required``. ``required=false`` means a registration submission is unnecessary and would fail. Fields and files require accurate information supplied by the authorized applicant. Choice fields accept comma-separated option keys within their ``min_choices`` and ``max_choices``. Field ``max_length`` uses UTF-16 code units; an emoji counts as two. Selected consent methods can require evidence even when shared fields are optional. Document slots with ``needs_input=false`` require no upload. An upstream failure returns an error.

List the workspace's saved agents and their settings. Agent records contain IDs, names, instructions, greetings, disclosure settings, voice settings, enabled channels, status, duration limits and handover contacts. Returns ``items`` or an error.

List recent workspace calls, newest first. ``cursor`` accepts the previous page's ``next_cursor``. Optional filters are ``status`` and the E.164 destination ``to``. Statuses include queued, dialing, ringing, in_progress, completed, failed, busy, no_answer and canceled. Returns ``items`` and ``next_cursor``.

List workspace members and manually saved contacts. ``q`` filters by name, email or phone. ``limit`` defaults to 100, with a maximum of 500. Returns ``items`` with ID, kind, name, phone_e164, email and role. Members have ``kind="member"``, an ID of ``member:<user_id>`` and a role. Manual entries have ``kind="manual"``, a UUID and no role.

List the workspace's sending identities and default sender address. Returns ``items``, ``next_cursor`` and ``default_from``. Only identities with ``verification_status="verified"`` can send. For ``kind="custom"``, ``domain`` is a domain supporting any local part. For ``kind="hail_mail"``, it is already a complete email address. One verified custom domain takes priority over the Hail mail address. With several verified custom domains, ``default_from`` is null and email sending requires an explicit sender.

List workspace email summaries, newest first. ``direction`` is ``inbound`` or ``outbound``. ``status`` is queued, sent, failed, bounced, complained or received. ``cursor`` accepts the previous page's ``next_cursor``. Summaries contain IDs and metadata, without message bodies. Returns ``items`` and ``next_cursor``, or an error.

List US state and Canadian province codes supported by number searches. Returns ``regions`` containing ``country_code``, ``code`` and ``name``. These codes identify the optional region filter for a city search. An upstream failure returns an error.

List dedicated workspace phone numbers, newest first. ``limit`` is 1 to 200, defaulting to 50. ``cursor`` accepts the previous page's ``next_cursor``. Items include ID, E.164 number, country, type, capabilities, provisioning state and assigned agents. Returns ``items`` and ``next_cursor``, or an error.

List recent workspace text messages. ``status`` filters by queued, sent, delivered, failed, undelivered or received. ``to`` filters by E.164 destination. ``cursor`` accepts the previous page's ``next_cursor``. Returns ``items`` and ``next_cursor``.

List workspace carrier registrations, newest first. ``purpose`` optionally selects ``number`` or ``sms`` registrations. Items include IDs, applicant names and types, country, number type, purpose, state, rejection details, timestamps, confirmation method and SMS progress fields. States are awaiting_review, submitting, submitted, approved, rejected or cancelled. SMS steps include confirm_identity, filing, carrier_review, needs_information and runtime_setup. ``campaign_accepted`` alone does not authorize texting: runtime readiness and number attachment are also required. ``identity_confirmed`` can carry over to a later filing for the same person. ``waiting_for_credit`` means a carrier fee prevents the next step. ``credit_needed_cents`` is that registration's share of the additional credit needed, or null when it is not waiting. Shares across waiting registrations are additive. ``confirmation="code"`` identifies a carrier-texted confirmation code. Returns ``items`` or an error.

Find workspace contacts by name, email or phone fragment. Returns up to ten matches containing names, phone numbers, email addresses and IDs. Several matches can refer to different people.

Start an outbound AI phone call. At least one of ``system_prompt``, ``llm`` or ``agent_id`` is required. An ``agent_id`` selects saved settings; explicit arguments override them. ``llm`` contains ``base_url``, ``api_key`` and ``model`` for a compatible endpoint. A supplied prompt becomes part of the call agent's instructions. ``to`` is an E.164 phone number. ``from_`` is optional and defaults to the first active number. ``first_message`` is spoken on pickup. Without it, the agent reacts to the answer or silence. ``language`` is a supported lowercase ISO 639-1 code; English is the default. An unsupported code returns 422. ``ai_disclosure`` is true by default and speaks an AI notice at the start of the call. ``ai_disclosure=false`` skips it. US artificial-voice calls (47 CFR 64.1200(b)(1)) require it. Hail does not verify the lawful basis. ``recording_enabled`` overrides the agent or workspace recording setting for this call. ``tools`` limits the call agent's capabilities; an empty list disables them. ``recipient_consent=true`` attests to the recipient's lawful consent. Other values are rejected. Hail does not verify consent. ``message_type="marketing"`` also requires ``consent_source``. ``metadata`` is stored on the call record. A returned ``idempotency_key`` identifies the original request for a retry. A different key represents a new call. A 4xx response returns no key. Returns the call ID, status, phone numbers and ``idempotency_key``, or an error.

Preview the campaign text for a US SMS registration without filing or charging. ``subject_type``, ``fields``, ``address`` and ``number_id`` describe the proposed application. The response contains the description, consent flow and samples for user review before submission. Answers require actual applicant information and consent evidence. Field or length errors appear in ``problems``. Limits are 100 fields and 64 KiB of combined fields and address. A successful preview does not guarantee submission: duplicates, low credit or carrier checks can still prevent it.

Compare available phone numbers and their prices without buying or charging. ``country_code`` is an ISO alpha-2 code, such as ``US``. ``capabilities`` selects voice, SMS or both. ``number_type`` is optional: local, mobile, national or toll_free. ``area_code`` is an area code or number prefix in national format. ``city`` is optional. ``region`` distinguishes US states or Canadian provinces. Offers include ``locality`` and ``region`` because city names can repeat. Returns ``offers``, ``recommended_quote_id`` and ``expires_at``. Each offer includes ``e164``, ``number_type``, ``capabilities``, ``quote_id``, ``monthly_cents``, ``setup_cents``, ``readiness``, ``requirements``, ``subject_types`` and ``verifications``. Prices are USD cents. Quotes expire after ten minutes. Expired quotes cannot authorize a purchase. ``recommended_quote_id`` identifies a ready offer or is null when none is ready. ``subject_types`` identifies eligible personal or business registrations. ``verifications`` contains accepted registrations, with approved entries first. Entries include ``id``, ``state``, ``subject_type`` and ``subject_name``. A purchase with several approved registrations requires an explicit ``verification_id``. ``readiness="verification_required"`` means registration approval is still needed. Registration requirements are specific to the quote and applicant type. An offer with ``by_request=true`` has no assigned number and requires a manual support order. Such offers remain valid for registration but are unavailable for automatic purchase. An upstream failure returns an error.

Permanently release a phone number after explicit user authorization. ``confirm_e164`` must match the number's E.164 value. A mismatch returns an error without releasing anything. Calls and texts to a released number stop. Recovery is not guaranteed. Current and previous monthly fees remain due, without a refund. Pending orders cannot be released and return 409. A failed order was not purchased; this operation only dismisses it from the list. Returns ``released`` or ``dismissed``, plus ``number_id`` and ``e164``, or an error.

Set the saved agents that answer a number's calls and texts. ``number_id`` identifies an existing workspace number. ``voice_agent_id`` selects the agent for incoming calls. ``sms_agent_id`` selects the agent for incoming texts. ``clear_voice=true`` or ``clear_sms=true`` removes the corresponding agent. Omitted settings retain their current values. Returns the updated number record or an error.

Send an email from a verified workspace sender. ``to`` is a non-empty list of email addresses. At least one of ``body_text`` or ``body_html`` is required. Open and click tracking requires an HTML body. Plain-text emails still have sending, delivery and bounce events. ``cc``, ``bcc`` and ``reply_to`` are optional. Hail supplies no default ``reply_to``. Without ``from_``, one verified custom domain takes priority over the Hail mail address. Several verified custom domains require an explicit ``from_`` address. When configured, a workspace without a sender receives a Hail mail address automatically. An explicit sender must match a verified workspace identity. ``from_name`` is an optional display name; control characters are rejected. ``attachment_ids`` contains IDs from uploaded email attachments. ``metadata`` is stored on the email record. ``recipient_consent=true`` attests to lawful consent. Other values are rejected. Hail does not verify consent. ``message_type="marketing"`` also requires ``consent_source``. A returned ``idempotency_key`` identifies the original request for a retry. A different key represents a new email. Returns the email ID, status, sender, recipients and ``idempotency_key``, or an error.

Send an outbound text message. ``to`` is an E.164 phone number and ``body`` is the message text. Without ``from_``, supported destinations use the workspace's alphanumeric sender ID. Other destinations use an eligible workspace SMS-capable number. A missing required number returns 422. SMS does not use the shared voice-call pool. US long-code texting to US recipients requires ready A2P 10DLC registration and an attached number. ``recipient_consent=true`` attests to lawful consent. Other values are rejected. Hail does not verify consent. ``message_type="marketing"`` also requires ``consent_source``. A returned ``idempotency_key`` identifies the original request for a retry. A different key represents a new message. Returns the SMS ID, status, sender, destination, segment count and retry key, or an error.

Submit authorized applicant details and documents for carrier registration. Submission is irreversible once sent for review. Carriers retain submitted documents. ``attest_authorized=true`` attests that the named person or business authorized this submission and supplied the actual details and files for it. False sends nothing. ``subject_type`` identifies that person or business and must match the requirements. ``fields``, ``address``, ``documents`` and ``files`` follow the carrier's current requirements. ``purpose="number"`` requires the same ``quote_id`` as the requirements response. The balance must cover the offer's setup fee plus first month; otherwise nothing is sent. That amount is reserved during review and pays for a later purchase using this registration. It is returned after rejection, cancellation or 30 days without purchase following approval. ``purpose="sms"`` registers a US number for outbound US texting and charges carrier filing fees. The same ``number_id`` identifies the sender when it was required for the form. SMS campaign text requires user review and approval before submission. ``address`` contains customer_name, street, city, region, postal_code and country_code when required. ``documents`` maps each needed slot to its selected ``option`` and ``fields``. ``files`` has one entry per required file: ``{slot, upload_id}`` with the ``id`` from ``create_file_upload`` (purpose ``verification_document``, uploaded within the last hour), or ``{slot, content_type, content_base64}`` for a very small file. With base64, every byte of the file is written into the tool call. Slot names match letters, digits, hyphens and underscores, up to 64 characters. Accepted files are JPEG, PNG or PDF: at most 10 MiB each and 20 files. Base64 files total at most 29 MiB, checked here; the API checks the 30 MB total of all files, uploads included. At most 100 fields are accepted. Base64 adds about one third to each file's size in the request. ``check_verification`` takes the same arguments and files nothing. Returns ``id``, ``state`` and ``subject_name``. Carrier review takes business days. A 409 identifies an existing registration; a timeout can leave a submission in progress. Carrier field errors include ``problems`` and leave no saved submission.

Update selected fields on a saved workspace agent. Omitted fields retain their values. Repeating the same update gives the same result. ``status`` is ``live`` or ``paused``; a paused agent does not answer. ``language`` is a lowercase ISO 639-1 code. Changing only language or voice preserves the other value. Call and handover duration limits are 60 to 3600 seconds. ``handover_contacts`` replaces the entire list with up to ten entries; an empty list removes them. Each entry contains ``contact_id`` and a note of 1 to 200 characters. ``clear_fields`` explicitly resets first_message, ai_disclosure_line, tools, max_duration_seconds or handover_max_duration_seconds. A field cannot be both set and cleared in the same request. Removing a greeting makes an inbound agent wait for the caller. Other resets restore workspace defaults; the handover limit resets to 1800 seconds. Existing calls keep their starting settings; changes affect later calls and texts. Returns the updated agent or an error.

Upload a small attachment for outbound email, as base64 text. Meant for small files (under about 50 KB): every base64 character goes through the tool call itself. Larger files go through ``create_file_upload`` with ``purpose="email_attachment"``: its ``curl`` line sends the bytes, and its ``id`` works in ``send_email``'s ``attachment_ids``. ``content_base64`` contains the file bytes encoded as base64. Returns ``id``, ``filename``, ``content_type`` and ``size_bytes``. The ID is accepted in an email's ``attachment_ids`` and is reusable across sends. Unused uploads expire after 24 hours. The combined message and attachments must fit the 25 MB sending limit.

Identify the account and organization authorized by the current credentials. Returns ``auth_kind``, ``organization_id``, ``user_id``, ``email`` and ``name``. Shared operator credentials have ``auth_kind="shared"`` with null user details. The response identifies the current actor, not a message recipient.