Skip to main content

Get started

Introduction

What the Finn API does, and what it does not.

What Finn is

Finn is a no-code platform for building AI voice agents that place and answer phone calls. You configure an agent (its prompt, voice, language, tools, and knowledge), attach a phone number, and Finn handles the telephony, speech recognition, model turn-taking, and speech synthesis for each call.

The API exists to automate what the dashboard already does. It is not a lower-level voice runtime. You do not stream audio frames, manage WebRTC sessions, or control turn detection through it. You create and configure agents, start and inspect calls, manage numbers and audiences, and read results after the fact.

If you have never built an agent before, start in the dashboard with quickstart-inbound or quickstart-outbound, then come back here to automate it.

What the API covers

AreaEndpointsNotes
Agentsapi-finnsCreate and update agent configuration
Deploymentsapi-deploymentsBind an agent to a number and a run configuration
Callsapi-callsStart outbound calls, read call records and transcripts
Audiencesapi-audiencesContact lists used by outbound runs
Phone numbersapi-phone-numbersList and inspect numbers on your account
Voicesapi-voicesList available voices
Webhooksapi-webhooksRegister endpoints for call events
Walletapi-walletRead balance and usage

Requests are authenticated with an API key sent as a bearer token. See authentication.

curl https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json"

const res = await fetch("https://api.hirefinn.ai/v1/finns", {
  headers: {
    Authorization: `Bearer ${process.env.FINN_API_KEY}`,
    "Content-Type": "application/json",
  },
});

if (!res.ok) {
  throw new Error(`Finn API ${res.status}: ${await res.text()}`);
}

const finns = await res.json();
console.log(finns);

import os
import requests

res = requests.get(
    "https://api.hirefinn.ai/v1/finns",
    headers={
        "Authorization": f"Bearer {os.environ['FINN_API_KEY']}",
        "Content-Type": "application/json",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Confirm the base URL for your account before copying these. It depends on your data region. See data-residency.

What the API does not cover

Some things are dashboard-only. Do not build against an endpoint you have not seen in the reference pages listed above.

TaskWhere it happens
Buying or porting a phone numberDashboard. The API lists and reads numbers, it does not purchase them
Billing, plan changes, adding creditsDashboard
Team members, roles, invitesDashboard
Compliance applications and number verificationDashboard, and often a manual review step
Building call workflows visuallyDashboard workflow editor

Beyond that, the API does not give you real-time audio. There is no endpoint that returns a live media stream, and no way to inject audio mid-call. What you get in real time is webhooks: events pushed to your endpoint as a call progresses and after it completes.

What will go wrong

Read these before you build anything that matters.

Calls are asynchronous. Creating a call returns once the request is accepted, not once the call is answered. The outcome arrives later through a webhook or by polling the call record. Code that treats a 2xx from the create endpoint as "the call succeeded" will report nonsense. See call-outcomes.

Concurrency is capped. Your account has a limit on simultaneous calls. Firing a thousand create requests does not produce a thousand simultaneous calls, and how the excess is handled is described in concurrency. This is separate from HTTP request rate limits, which are covered in api-rate-limits.

Retries can double-dial. A network timeout on a create-call request does not tell you whether the call was created. Send an idempotency key on every write. See api-idempotency.

Webhook deliveries repeat. Your endpoint must verify signatures (webhook-security) and tolerate duplicate deliveries (webhook-retries).

Telephony fails in ways HTTP does not. Busy, no answer, voicemail, carrier rejection, and spam labelling are normal outcomes, not bugs. troubleshooting covers the common ones.

Where to go next