> ## Documentation Index > Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Calling a Lead > Call a lead from your own phone using your organization's number — Erdo rings you, you press 1, and it dials the lead, with the whole call recorded and transcribed like any other. # Calling a Lead Your team can call a lead **from your organization's phone number** without giving out their own. Erdo rings the salesperson's mobile first; when they answer and press 1, Erdo dials the lead and connects the two. The lead's phone shows your organization's number, so calling it back reaches your [voice agent](/voice) as usual. It is an ordinary phone call for the person placing it — earpiece, lock screen, other apps, call waiting — because their own phone is what rings. That matters when the sales desk is a mobile, which it usually is. The call is kept like every other: it appears in your [call records](/voice-call-records) and on the lead's timeline, with who placed it, how long it lasted, what happened, and a transcript of both sides. This is a person talking to a lead. It is not the [live transfer](/voice#live-transfer-a-call-to-a-real-person), where your AI agent is already on a call and hands it to a colleague, and it is not an AI call — the agent is not on the line at all. ## Before you start * Your organization needs a [voice agent with its own phone number](/voice#give-an-agent-its-own-phone-number-inbound-calls) that Erdo bought and manages for you. A number you already owned and only told Erdo about cannot be called from: Erdo holds no credential for the account it lives on, and says so if you try. * Which countries can be reached is set on the phone account, not in Erdo. If a destination is not enabled, the call is refused and the record says exactly why, in the provider's words. * The salesperson needs a phone number of their own for Erdo to ring. Nothing connects until somebody answers it and presses 1. ## What happens, in order 1. Somebody presses **Call** on a lead. 2. Erdo checks that the number being called from is one of your organization's own agent numbers, and that the lead is not on your do-not-call list. 3. The salesperson's phone rings, showing your organization's number. 4. They answer and hear "Press 1 to call Maria Lopez". 5. On the key press, Erdo dials the lead. The lead's phone rings about ten to fifteen seconds after the button was pressed, because of steps 3 and 4. 6. When the call ends, the record is updated, and the transcript appears a minute or two later. A voicemail greeting cannot press 1, so a ring that goes to voicemail ends there — the lead's phone never rings and is never connected to a voicemail box. ## What the record says A call somebody placed by hand carries two fields the AI agent's calls do not: | Field | What it tells you | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `placed_by_name` | Who placed it. Empty on every call the AI agent placed and on every inbound call. | | `dial_outcome` | What became of the **lead's** side: `answered`, `no_answer`, `busy`, `failed`, or `canceled` — the last meaning the lead was never dialled, because the person did not answer their own phone or did not press 1. | `dial_outcome` is not the same as `status`. A call can be `completed` with a `no_answer` outcome: the call happened, it just reached nobody. The duration is how long the two people were actually on the phone together, so a call nobody answered lasts zero seconds. Both fields appear everywhere calls do — the [call records](/voice-call-records) list and read, the `erdo voice calls list` output, and the `erdo_voice_call_list` / `erdo_voice_call_get` MCP tools. ## The transcript Both sides are recorded on separate channels and transcribed separately, then merged back into one conversation in time order — so who said what is a fact about which phone the audio came from, not a guess. It reads like any other call's transcript: the person who placed the call is the `agent` side and the lead is the `user` side. If transcription fails — the transcription service is briefly unavailable, say — Erdo tries again on its own, over roughly the next day, so a transcript can arrive hours after the call rather than a minute or two. The call's outcome and duration are recorded straight away either way. The summary says what was discussed, what was agreed and any next step, naming the person who placed the call. It is written in English whatever language the call was in, like every other call summary. The audio itself stays with the phone provider. Erdo keeps the transcript and the summary, and nothing in Erdo plays or hands out a recording. ## Placing a call over the API `POST /v1/voice/person-calls`, with your organization's API key. There is no CLI command and no MCP tool for it, deliberately: the call rings a phone a specific person has to be holding and answer within about thirty seconds, so an agent or a scheduled script that "placed a call" would have started something only a human can finish. Reading calls back stays available everywhere. ```bash theme={null} curl -X POST https://api.erdo.ai/v1/voice/person-calls \ -H "Authorization: Bearer $ERDO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from_number": "+13055550100", "to_number": "(305) 555-0142", "recipient_name": "Maria Lopez", "canonical_lead_id": "0YQ0mBGRmvJRWWrDsPBQaB", "placed_by": { "ref": "user_2abc...", "name": "Ana" }, "person_phone": "+13055550188", "prompt_language": "es" }' ``` * `from_number` is the organization's number to call from, and what the lead sees. The numbers it can be are listed in `person_call_numbers` on `GET /v1/voice/phone-numbers` (and the `erdo_voice_phone_number_list` MCP tool): offer only those, and no call is refused for its number. * `to_number` is the lead, in any format — Erdo normalises it. * `canonical_lead_id` is the lead, as its UUID or its 22-character [lead reference](/lead-identity). It is required, because it is how the call reaches that lead's timeline. * `placed_by.ref` is your own stable identifier for the person placing the call. Erdo never resolves it; it uses it to hold them to one call at a time, and shows `placed_by.name` on the record. * `person_phone` is the phone Erdo rings first. It is **not** stored on the call record. * `prompt_language` is the language of the "press 1" prompt: `en` (the default), `es` or `pt`. Any other value is rejected with a `400` (`invalid_argument`) rather than spoken in a language the person may not understand. A successful response says which call was started and what Erdo is about to dial: ```json theme={null} { "call_id": "pcall_7k2m...", "from_number": "+13055550100", "to_number": "+13055550142", "to_country": "US", "person_phone": "+13055550188", "person_country": "US", "prompt_language": "es", "refused": false } ``` Read the call back with `GET /v1/voice/calls/{call_id}` as it progresses and once it is over. ### Numbers without a country code A number with no `+` country code is read as **US or Canada**. A ten-digit Colombian or Mexican mobile typed without its country code looks exactly like a US number, and Erdo cannot tell the difference — which is why the response always says the number it is about to dial and the country it belongs to. Show that to whoever pressed the button; they are the only one who can spot it. A number that is not valid under that reading is refused rather than dialled. ### When Erdo will not place the call The response comes back with `refused: true` and a `reason` you can branch on, plus a `message` you can show: | `reason` | What happened | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number_not_managed` | `from_number` is not one of this organization's voice agent numbers. | | `number_externally_managed` | The number is on an account Erdo does not manage, so there is no credential to call with. | | `lead_suppressed` | The lead is on your do-not-call list. | | `invalid_number` | One of the numbers is not something Erdo can dial. The message names which. | | `call_in_progress` | That person already has a call running. One at a time. | | `provider_refused` | The phone provider would not place the call — the message carries its own words, such as a destination the account is not authorised to call. The attempt is still recorded, as a failed call. | | `not_available_here` | Phone calling runs only in production, where your organization's phone numbers live. | A refusal is always a `200`. If the phone provider rejects the platform's own telephony credentials, that is not a refusal of your call — nothing about the lead's number or your settings was judged — so the request fails with a `503` (`unavailable`) instead, and the attempt is recorded as a failed call. It is a problem on Erdo's side; report it rather than changing anything or retrying. ## Good to know * **Only the do-not-call list blocks a call.** Quiet hours and rate limits exist to bound what an automation does unattended; when to call a lead is the judgement of the person picking up the phone. If you want a warning about the lead's local time, that belongs in the surface with the button, not here. * **Two legs cost about twice a single call**, and more when the salesperson's own phone is abroad. The usage lands on your organization's own phone account. * **A missed ring looks like a call from your own number.** Somebody who misses it and calls back reaches your voice agent. Saving the number as a contact is worth suggesting to the team. * **A call is capped at one hour**, so one left open on a desk cannot run up minutes indefinitely. * **Calls are not announced as recorded.** Some jurisdictions require every party's consent to a recording; that applies equally to your AI agent's calls today, and is worth checking against where you operate.