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 three 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 in your workspace | Settings → Phone numbers, or phone-numbers. Renting one needs an approved compliance application. | Nothing to dial from |
| A destination number in E.164 | You supply it | Call is never dialed |
Finn doesn't register numbers with carriers. A number that carriers label as spam keeps dialing, but answer rates collapse, so check its Health before you judge whether the Finn works. See spam-labeling and telephony-overview.
The fastest path: a test call
The quickest single call does not involve the API at all. Open your Finn in the dashboard, click Test → Phone 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 opening sounds wrong. The welcome message is always the first thing the Finn says, word for word. Rewrite it to name the caller, the company and the reason for the call. See agents-welcome.
- The Finn answers in the wrong language. Check the Finn's default language and the language your prompt is written in. See agents-multilingual.
Placing the call from the API
Place a single call with POST /api/v1/calls. The request and response fields are documented in api-calls. Take field names from that page, not from the dashboard network tab.
Three things apply to every call you place this way:
- 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.
- There is no idempotency key. Retrying a call request whose outcome you do not know 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 its status, duration and sentiment, and its transcript once it connects. See call-logs.
Receive a webhook. Add a webhook endpoint and get a call.completed event pushed to you after the call ends. 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. Finn does not enforce calling hours for you, 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.