Developer docs
Build voice agents on Finn
Quickstarts, guides and the REST reference for the Finn v1 API. New here? The API quickstart takes you from an API key to a finished, analyzed call.
Get started
Introduction
What the Finn API does, and what it does not.
Quickstart: the API
API key to a finished call in curl: voice, Finn, audience, deployment, webhook.
Quickstart: answer a call
Point a number at an agent and take a real call.
Quickstart: place a call
Place one call: a test to yourself, or one through the API.
Concepts
Finns, deployments, audiences, calls — and how they relate.
Agents
Quickstart: build an agent
From Start from scratch to an agent that answers correctly on a test call.
Agent configuration
The parts of a Finn and where each one is configured.
Identity and persona
Name, use case, and the identity text the model acts from.
Prompting
Writing instructions that survive a real phone call.
Style and guardrails
Stopping the model improvising into claims you cannot keep.
Welcome messages
The first line every call opens with, and how to write it.
Variables
Filling {{ column }} placeholders from your audience.
Voice and speech
Choosing a voice, matching it to the language, and testing it.
Text to speech
The TTS layer, its default, and when to change it.
Speech to text
Transcription settings, languages and accent handling.
Language model
Choosing the model behind the conversation.
Multiple languages
One language per Finn, and serving callers who speak several.
Conversation behaviour
Silence, reminders and call length.
Knowledge base
Grounding answers in your own content.
Call flows
When to use a call flow instead of a prompt, and its steps and tools.
Testing an agent
Trying it before a real caller does.
Examples
Worked agents for the common jobs, and why each is shaped that way.
Tools and integrations
Tools overview
How an agent takes action during a call.
Built-in tools
Check Calendar, Book Calendar and Call Transfer.
Custom tools
Calling your own endpoint from inside a conversation.
Transfers
Cold handoff to a person with the Call Transfer tool.
Workflow editor
Building a call flow on the canvas, step by step.
Workflow nodes
Start, Conversation and End Call steps, and transitions.
Workflow variables
Contact data in a call flow, and what step prompts can't read.
Testing a workflow
Finding the dead branch before a caller does.
Integrations overview
What connects natively and what needs a webhook.
CRM integrations
Zoho lead intake, and getting call results into any CRM.
Calendar integrations
Booking on Cal.com during a call.
Messaging
Post-call reports, and email, SMS and WhatsApp senders for sequences.
MCP server
Driving Finn from an AI assistant over MCP.
Telephony
Telephony overview
What happens between the caller and the agent.
Phone numbers
Renting, assigning and managing numbers.
Bringing your own number
Using your own carrier account on a number.
Number capabilities
What a given number can and cannot do.
Number pools
Spreading volume across numbers, and why.
Spam labeling
Why calls get flagged, and what actually fixes it.
Inbound routing
One number to one Finn, and routing callers onward.
Outbound campaigns
Launching, pacing and monitoring a deployment.
Cadences and sequencing
Multi-attempt follow-up over days, not one call.
Concurrency and limits
How many calls run at once, and what happens past that.
Call outcomes
Every way a call can end, and what each means.
Observability
Call logs and artifacts
Recordings, transcripts and where they live.
Post-call analysis
Structured outcomes extracted from a conversation.
Defining analysis fields
Answer types, wording and editing fields after launch.
Metrics
The numbers that tell you whether it is working.
Exports
Getting call data out for your own analysis.
Evaluations
Testing an agent before it answers a real caller.
Monitoring
The live deployment view and what to alert on.
API reference
Conventions
Base URL, response envelope, IDs, timestamps, versioning.
Errors
Every error code, its status and what to retry.
Pagination and filtering
limit and offset, page size caps and the filters that exist.
Rate limits
Per-key limits for each endpoint group, headers and backoff.
Idempotency
No idempotency key: how to retry each write safely.
Finns
Create, read, update and delete voice agents.
Deployments
Campaigns and inbound bindings.
Calls
Placing calls and reading call records.
Audiences
Contact lists and their members.
Phone numbers
Owned and rented numbers.
Voices
Listing available voices.
Webhook subscriptions
Endpoints, the call.completed payload and delivery.
Wallet
Balance and transactions.
Security and compliance
Authentication
API keys, organization access and rotation.
Data residency
Where your call data is stored, and asking for a region.
Retention and deletion
How long artifacts are kept, and how to remove them.
Compliance overview
What the platform covers and what stays your obligation.
Rules by region
What changes when you call across a border.
Rules by industry
Healthcare, finance, collections and legal.
Recording consent
Disclosure, opt-out and per-jurisdiction rules.
Server integration
Webhooks overview
Receiving call events on your own server.
Inbound call webhook
Synchronous routing before a call connects. Not available yet.
Post-call webhook
The call.completed payload, field by field.
Event reference
The events Finn sends and when they fire.
Verifying webhooks
Signatures, replay windows and secret rotation.
Delivery and retries
Timeouts, the retry schedule and recovering missed events.
Local development
Tunnelling, replaying events and test calls.