The four objects
Everything on the platform is built from four objects. Learn how they relate and the rest of the documentation follows.
Finn + Audience + Phone number + Schedule = Deployment
Deployment → Calls → Transcripts + structured fields
| Object | What it is | Lives for |
|---|---|---|
| Finn | The agent: voice, language, instructions, knowledge, tasks | Until you delete it |
| Audience | A contact list with a name, phone number, country code, and any custom fields you add | Until you delete it |
| Deployment | One campaign instance putting a Finn on real calls | From launch until it stops or completes |
| Call | A single conversation, inbound or outbound | The duration of the call, plus its stored record |
Finn
A Finn is the agent. It holds identity text, style and guardrails, response guidelines, welcome message, custom vocabulary, voice, language, time zone, knowledge base, optional workflow, tasks, call settings, and post-call analysis fields.
A Finn does not make calls on its own. It is configuration. Nothing is live until a deployment references it.
Edits to a Finn apply to new calls only. Calls already in flight finish under the config they started with, so a mid-campaign edit produces a mixed set of results. The platform keeps configuration history, so you can roll back a change that degrades performance.
See agents-overview, agents-prompting, and agents-knowledge-base.
Audience
An audience is a contact list. Required columns are name, phone_number (local digits, no country code, no formatting), and country_code (with a leading +).
Any extra column becomes a custom field the Finn can reference mid-call with {{field_name}} syntax. This is how personalization works. There is no separate personalization system.
Contacts arrive by CSV upload, CRM sync (HubSpot, Salesforce, Pipedrive), or manual entry. Deduplication is on the (country_code, phone_number) pair and the first occurrence wins. Numbers on the account-level do-not-call list are dropped from every deployment silently, no matter which audience holds them.
Within an audience you can define segments, which are filters over custom fields. Segments are dynamic and re-evaluate as contacts change, so a deployment pointed at a segment picks up new matches without you re-importing.
| Plan | Max contacts per audience | Max audiences |
|---|---|---|
| Starter | 5,000 | 10 |
| Growth | 50,000 | unlimited |
| Enterprise | unlimited | unlimited |
See api-audiences.
Deployment
A deployment is the join between a Finn, an audience, a from-number, and a schedule. It is the only object that spends money.
One Finn can back many deployments at once against different audiences or schedules. They run independently and do not share state, retry counters, or pacing.
Deployment types:
- Standard — dials one at a time or in small concurrent batches, bounded by your plan's concurrency.
- Parallel — dials at high concurrency. Requires enough phone-number capacity. One number cannot carry thousands of simultaneous calls, so you need a number pool first. See phone-numbers and concurrency.
- Scheduled — either type, held until its start time, then transitioned to live automatically.
Calling-hour windows are evaluated in each contact's local time, not yours. A deployment that runs for three days with a 9 AM to 6 PM window will call an Indian contact and a US contact at different absolute times. If the time zone cannot be derived from the country code, the platform falls back to the deployment default, which is a common source of calls landing at the wrong hour.
Pause stops new dialing and lets active calls finish. Stop does the same and marks the deployment completed, which is not reversible. Active calls are never cut mid-conversation.
Launching and pausing are done in the dashboard under Dynamic Deployments, Scheduled Deployments, and Live Deployments. See outbound-campaigns and api-deployments.
Call
A call is one conversation. Every call produces a transcript, an outcome status, and the structured fields you defined in the Finn's post-call analysis tab.
Those fields are the measurement layer. If you launch without defining any, you get transcripts and nothing you can aggregate, and you cannot answer "how many booked?" without reading calls by hand. Define them before launch, not after.
Failed calls (no answer, busy, voicemail) are retried according to the deployment's retry policy, and retries land in the next valid calling-hour window for that contact rather than immediately. If voicemail behavior is set to leave a message, the platform plays the message and does not retry.
See call-outcomes, call-logs, and post-call-analysis.
How the pieces fail together
| Symptom | Which object is wrong |
|---|---|
| Finn greets with silence | Finn — welcome message set to defined with an empty script |
| Right script, wrong name in greeting | Audience — name column missing or misnamed |
| Calls placed at 3 AM local | Deployment — calling hours, or an unresolvable contact time zone |
| Carrier rejects every call | Phone number — not registered for the destination country |
| Deployment pauses on its own | Deployment — audience exhausted or a spend cap hit |
See troubleshooting.
Next
Build one of each end to end: quickstart-inbound or quickstart-outbound.