Developer docs
Build voice agents on Finn
Quickstarts, guides and the REST reference. The API is in beta — shapes can change, and each reference page says what is settled and what is not.
Get started
Agents
Quickstart: build an agent
From empty wizard to an agent that answers correctly.
Agent configuration
The parts of a Finn and which are editable at runtime.
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
Dynamic versus defined openings, and when each is required.
Variables
Passing per-call context into a prompt.
Custom vocabulary
Teaching the recogniser your product and place names.
Voice and speech
Voice selection, pacing, interruption and pronunciation.
Text to speech
The TTS layer, its default, and when to change it.
Speech to text
Transcription, language groups and accent handling.
Language model
Choosing the model behind the conversation.
Multilingual calls
Detecting and switching language mid-call.
Conversation behaviour
Silence, re-prompts, interruption and call length.
Voicemail detection
Recognising a machine, and what to do about it.
Knowledge base
Grounding answers in your own content.
Tasks and workflow
Giving an agent a sequence to complete, not just a topic.
Testing an agent
Trying it before a real caller does.
Editing and versioning
Changing a live agent without breaking the calls in flight.
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
Transfer, end call, book, look up, send message.
Custom tools
Calling your own endpoint from inside a conversation.
Transfers
Warm and cold handoff to a person.
Workflow editor
Building a branching call flow node by node.
Workflow nodes
Every block type and what it does.
Workflow variables
Carrying data from one node to the next.
Testing a workflow
Finding the dead branch before a caller does.
Workflow versioning
Undo, reuse and sharing flows between agents.
Integrations overview
What connects natively and what needs a webhook.
CRM integrations
Writing call outcomes into your system of record.
Calendar integrations
Booking against live availability.
Slack and automation
Notifications, Zapier, Make and n8n.
MCP server
Driving Finn from an AI assistant over MCP.
Telephony
Telephony overview
What happens between the caller and the agent.
Phone numbers
Buying, assigning and managing numbers.
Bringing your own number
Porting or pointing a number you already own.
Number capabilities
What a given number can and cannot do.
Number pools
Spreading volume across numbers, and why.
Caller ID registration
CNAM, STIR/SHAKEN and getting your name to display.
Spam labeling
Why calls get flagged, and what actually fixes it.
Inbound routing
Business hours, overflow and fallback.
Outbound campaigns
Batch calling, pacing and retries.
Cadences and sequencing
Multi-attempt follow-up over days, not one call.
WhatsApp calling
Taking calls over WhatsApp instead of the PSTN.
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.
BYOC and SIP
Bringing your own carrier or trunk.
Server integration
Webhooks overview
Receiving call events on your own server.
Inbound call webhook
Answering Finn synchronously before the call connects.
Post-call webhook
The payload delivered after a call completes.
Event reference
Every event, its payload and when it fires.
Verifying webhooks
Signatures, replay windows and rotation.
Delivery and retries
Timeouts, backoff and idempotency on your side.
Caller pre-screening
Deciding how to greet someone before they speak.
Local development
Tunnelling, replaying events and test numbers.
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
Latency, answer rate and what to alert on.
Security and compliance
Authentication
API keys, scopes and rotation.
Single sign-on
SAML and directory access for a workspace.
Data residency
Choosing the region your call data lives in.
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.
API reference
Conventions
Base URL, versioning, IDs, timestamps.
Errors
Status codes, error bodies and what to retry.
Pagination, filtering and sorting
Working through large collections.
Rate limits
Limits, headers and backoff.
Idempotency
Making a retried write safe.
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
Registering and managing endpoints.
Wallet
Balance and transactions.