What this page covers
Placing one outbound call, either as a test to yourself or as the smallest possible real call. If you want to run a call against a list of contacts, that is a deployment, and it is covered in outbound-campaigns.
Before you start
You need four things in place. Missing any one of them is the most common reason a first call never connects.
| Requirement | Where it comes from | What breaks without it |
|---|---|---|
| A saved Finn | Create New Finn in the dashboard, or api-finns | Nothing to run on the call |
| A from-number assigned to your account | Settings → Phone numbers, or phone-numbers | Carrier rejects the call |
| Number registered for the destination country | Carrier registration, per country | Calls fail with a carrier rejection |
| A destination number in E.164 | You supply it | Call is never dialed |
For US destinations, an unregistered from-number gets labeled as spam and answer rates collapse. Register the number before you judge whether the Finn works. See telephony-overview.
The fastest path: test on call
The quickest single call does not involve the API at all. Open your Finn in the dashboard and click Test on Call, then enter your own phone number. The Finn calls you within a few seconds.
This is a dashboard action, not an API endpoint. Use it to check the welcome message, the voice, and the opening turn before you wire anything up. Treat it like a real conversation. Interrupt it, give it confusing input, ask it something the knowledge base does not cover. Most first-call problems are prompt problems, and they surface here faster than in any log.
Two failure modes show up immediately:
- The call connects and the Finn says nothing. The welcome message is set to defined and the script is empty. Set it to dynamic or write the verbatim line. See agents-prompting.
- The Finn answers in the wrong language. A
language_groupfield or a timezone on the contact is overriding the Finn's default. See agents-multilingual.
Placing the call from the API
The request and response contract for triggering a single call is not yet settled in this documentation set. Do not copy a payload shape from another page or infer one from the dashboard network tab, because it is not stable. The endpoint reference lives at api-calls, and that page is the only place the field names should be taken from.
What is settled and will not change underneath you:
- Authentication is the same for every endpoint. See authentication.
- Error envelope, status codes, and retry semantics are shared. See api-errors and api-rate-limits.
- Repeating a call trigger without an idempotency key can dial the same person twice. See api-idempotency.
That last point matters more for calls than for most resources. A duplicated write to a database is an annoyance. A duplicated call is a second phone ringing in someone's pocket.
What happens after the call is placed
The call is dialed, the conversation runs, and the call ends with an outcome. You learn the outcome one of two ways.
Poll or read the log. The call appears in Call History with transcript, audio recording, duration, and sentiment. See call-logs.
Receive a webhook. Subscribe to call lifecycle events and get the result pushed to you when the call completes. This is the right choice if anything downstream depends on the outcome. See webhooks and webhook-events.
Structured fields you defined for post-call analysis, such as whether an appointment was booked, are attached to the completed call. If you have not defined any, you get a transcript and no way to measure success. Define them before you scale past a handful of calls. See post-call-analysis.
Things that will bite you
- No answer is normal. Cold lists run 30 to 50 percent pickup. Warm reminders run 70 to 85 percent. A single test call that goes unanswered tells you nothing.
- Calling hours apply to real recipients. Never dial before 8 AM or after 9 PM in the recipient's local time. Most jurisdictions add their own restrictions. A single API-triggered call bypasses the campaign-level calling-hour window, so the timing is yours to get right. See compliance.
- You need a lawful basis to call. Explicit consent for marketing, or an existing relationship for informational calls.
- Recording has its own rules. If you record, disclosure requirements vary by jurisdiction. See recording-consent.
- Concurrency is capped by your plan. One call will not hit it. A loop over a list will. See concurrency.
Next
- quickstart-inbound for a Finn that answers instead of dials.
- outbound-campaigns for calling a list rather than one number.
- call-outcomes for what each terminal status means.