> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt > Use this file to discover all available pages before exploring further. # Quick Agent Actions > Call, text, or stand up an AI phone number in one API call — no phone number to buy first. Quick Agent Actions are the shortest path from "an AI agent wants to reach someone" to a real phone call or text. There is no number to provision, no assistant to configure, and no campaign to build: you send a goal, LumisReach runs the conversation, and you poll one endpoint for the outcome. Everything here runs on Telnyx + LiveKit, the same stack behind the rest of the platform. An AI agent calls one or more numbers from a shared LumisReach number and works toward your goal, with retries when nobody picks up. An AI agent opens an SMS thread from a registered shared sender and keeps answering replies until the goal is met. Buy a number and configure the agent that answers it — calls and, optionally, texts — in a single request. ## Shared senders Quick calls and quick texts go out from numbers LumisReach owns, on the LumisReach Official account. That is what removes the setup step: you do not buy a number, register a brand, or wait for provisioning before your first call. What this means in practice: * **The recipient sees a LumisReach number**, not one of yours. A single job can go out from more than one number — each destination reports its own `from_number` — so no single number carries an entire job. * **Texts are already registered.** The shared SMS senders sit on LumisReach's approved A2P 10DLC campaign, so the first message is registered traffic rather than filtered traffic. * **Everything the conversation produces is yours.** Call records, recordings, transcripts, messages and contacts are written into your workspace, scoped to your organization like any other data. * **Replies come back to us, not to you.** A shared number cannot ring your phone. When someone needs to be able to call or text you back, provision your own number with [`POST /v1/quick/ai-numbers`](/api-reference/quick-agent-actions#buy-a-number-with-an-ai-agent). ### Daily limits Carriers flag a number that places too many calls in a day, and a flagged shared number would degrade every account using the pool. So each shared number has a daily ceiling, and the pool spreads work to stay under it: * **Calls:** up to 75 per number per day once the number is warmed up. A number bought in the last week is held to 15/day and 40/day in its second week, the same ramp outbound campaigns use. * **Texts:** up to 500 outbound messages per number per day. * **Selection:** each leg draws a number at random from those that still have room, weighted by how much room is left, so traffic self-levels instead of piling onto one number. A number at its ceiling is not used again until the next day — including for a retry that comes due after the number filled up. If the whole pool is exhausted, the request returns **409** with `Every shared LumisReach … number has reached its daily volume limit`; destinations a job could not cover are recorded with `end_reason: "shared_pool_daily_limit"` rather than dropped. Provision your own number with `POST /v1/quick/ai-numbers` when you need volume beyond what the shared pool allows. ## Pricing Quick actions are priced per action and charged to the wallet of the organization that owns the API key you authenticate with. They do not draw down plan-included minutes or messages — the shared sender carries no line fee, so the usage is billed à la carte. | Action | Price | | --------------------- | -------------------------------------------------------------------------------- | | Quick AI phone call | **$0.20 per call placed** + **$0.20 per minute** of conversation | | Quick AI text message | **\$0.05 per outbound message** | | AI phone number | **\$5 per month** for the line (calls and texts on it bill at your plan's rates) | The $0.20 call fee is charged when the call is **placed**, not when it is answered — and each retry is a new placed call. A job with `retry_attempts: 2` that never reaches anyone costs $0.60. Talk time is billed by the second at the per-minute rate. For texts, only **outbound** messages are billed; replies from the recipient are free. If the wallet balance runs out mid-job, auto-recharge fires if it is enabled on the account; otherwise the account pauses and remaining attempts stop. Check your balance and top-up settings under **Settings → Billing**. ## Place an AI call ```bash theme={null} curl -X POST https://api.lumisreach.com/api/v1/quick/ai-calls \ -H "Authorization: Bearer $LUMISREACH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to_numbers": ["+14155550123"], "goal": "Confirm that Dana still wants the 3pm Thursday appointment, and reschedule to Friday if not.", "opening_message": "Hi, this is Ada calling from Northside Dental about your appointment.", "retry_attempts": 2, "retry_delay_minutes": 15, "voice": "marin" }' ``` ```json theme={null} { "data": { "id": "0f3c...c81", "kind": "ai_call", "status": "running", "from_number": "+14153261744", "target_count": 1, "status_url": "/api/v1/quick/actions/0f3c...c81", "pricing": { "start_fee_usd": 0.2, "per_minute_usd": 0.2, "note": "Charged per initiated call (including each retry), plus per-second conversation time at the per-minute rate." } } } ``` The response returns as soon as the first attempt is dialing. Retries are automatic: if a number rings out, goes to voicemail, or is busy, the agent tries again after `retry_delay_minutes` until `retry_attempts` is exhausted. ### What you can configure | Field | What it does | | ---------------------------------------- | --------------------------------------------------------------------- | | `goal` | The spine of the system prompt. Write it as an outcome, not a script. | | `instructions` | Tone, facts the agent may state, objections to expect. | | `opening_message` | What the agent says first, once the recipient speaks. | | `voice`, `voice_model_tier`, `language` | Voice selection and language. | | `retry_attempts`, `retry_delay_minutes` | How persistently to chase an unanswered number. | | `max_call_duration_seconds` | Hard stop on call length (default 10 minutes). | | `voicemail_enabled`, `voicemail_message` | Whether to leave a voicemail, and exactly what to say. | | `contact_name` | Used for `{{CONTACT_NAME}}` in the conversation. | ## Send AI text messages ```bash theme={null} curl -X POST https://api.lumisreach.com/api/v1/quick/ai-texts \ -H "Authorization: Bearer $LUMISREACH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to_numbers": ["+14155550123"], "goal": "Find out whether they still want the quote, and if so which day next week works for a call.", "first_message": "Hi Dana, it is Ada at Northside. Still want that quote? Happy to send it over.", "max_messages": 4 }' ``` Omit `first_message` and the agent writes the opener from the goal. After that it answers each reply on its own until the goal is met, `max_messages` outbound messages have been sent, the recipient goes quiet for `conversation_timeout_hours`, or they text STOP. **STOP is honored automatically** and the thread ends immediately. Opt-out language is appended to the first message to a new recipient. Text only people who have agreed to hear from you — the shared sender carries LumisReach's 10DLC registration, and a complaint against it affects every account using it. ## Check on a job Both kinds of job report through the same endpoint. ```bash theme={null} curl https://api.lumisreach.com/api/v1/quick/actions/0f3c...c81 \ -H "Authorization: Bearer $LUMISREACH_API_KEY" ``` ```json theme={null} { "data": { "id": "0f3c...c81", "kind": "ai_call", "status": "running", "goal": "Confirm that Dana still wants the 3pm Thursday appointment...", "from_number": "+14153261744", "targets": [ { "to_number": "+14155550123", "from_number": "+14153261744", "status": "in_progress", "live_call_status": "ringing", "attempts": 1, "last_call_id": "b91e...4af", "messages_sent": 0, "messages_received": 0, "goal_achieved": false, "end_reason": null, "summary": null } ], "counts": { "total": 1, "pending": 0, "in_progress": 1, "completed": 0, "no_answer": 0, "failed": 0, "opted_out": 0, "canceled": 0 }, "created_at": "2026-09-19T17:02:11.480Z", "completed_at": null } } ``` A target's `status` is one of `pending`, `in_progress`, `completed`, `no_answer`, `failed`, `opted_out` or `canceled`. While a call is live, `live_call_status` reports what the call itself is doing (`ringing`, `in_progress`, …) so polling shows the call as it happens. `end_reason` explains how a finished target ended: `answered`, `goal_achieved`, `voicemail`, `max_attempts`, `max_messages`, `opted_out`, `canceled`, `shared_pool_daily_limit`, or the provider's error text. `from_number` is the shared number that particular destination was reached from. To stop a job early, `POST /v1/quick/actions/{id}/cancel`. Remaining dials and AI replies stop; a call that is already connected is allowed to finish. ## Buy a number with an AI agent When people need to reach *you* — an inbound line, a number on a listing, a callback number — buy one and configure its agent in the same request: ```bash theme={null} curl -X POST https://api.lumisreach.com/api/v1/quick/ai-numbers \ -H "Authorization: Bearer $LUMISREACH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "area_code": "415", "name": "Support line", "business_name": "Northside Dental", "business_description": "A family dental practice in San Francisco. Cleanings, fillings, crowns, Invisalign.", "greeting": "Thanks for calling Northside Dental, this is Ada. How can I help?", "handle_calls": true, "handle_texts": true }' ``` `handle_calls` (default `true`) controls whether the AI answers inbound calls. `handle_texts` (default `false`) puts the same agent on inbound SMS for that number. Provisioning is asynchronous — poll until it reports `ready`: ```bash theme={null} curl https://api.lumisreach.com/api/v1/quick/ai-numbers/42 \ -H "Authorization: Bearer $LUMISREACH_API_KEY" ``` ```json theme={null} { "data": { "id": 42, "phone_number": "+14155551234", "status": "ready", "handles_calls": true, "handles_texts": true, "sms_registered": true, "agent": { "id": "8c1d...7b2", "name": "Northside Dental", "voice": "marin", "language": "en", "greeting": "Thanks for calling Northside Dental, this is Ada. How can I help?", "prompt": "..." } } } ``` `status` moves `provisioning` → `ready`, or `failed` if the number could not be wired up. While it is provisioning, `phone_number` is `null`; once it is `ready`, the number is live and answering. ## Authentication Quick Agent Actions use the same Bearer API key as the rest of the v1 API. A key created under **Settings → Developer API** works on every endpoint on this page with no extra configuration. See [Authentication](/api-reference/authentication). ## Using these from an AI agent Every action on this page is also exposed as a tool on the LumisReach MCP server, so an agent can call, text, and provision numbers without you writing HTTP glue. See [MCP server](/api-reference/mcp).