Developer docs
Build voice agents on Finn
Quickstarts, guides and the REST reference for the Finn v1 API. Create an API key in Settings → Integrations to get started.
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
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.
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, organization access 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, 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.