Skip to main content

Finn Voice API

Programmatische toegang — auth, endpoints, webhooks.

7 min read

Finn Voice API

De Finn API is hetzelfde oppervlak dat ons dashboard gebruikt. Bouw stem agenten, lancering campagnes, inname analytics, allemaal programmatisch.

Deze gids brengt u naar uw eerste live API bellen in ~5 minuten.

Snelstart (3 stappen)

1. Pak een API sleutel

Dashboard → Instellingen → Integraties → API Sleutels → Sleutel genereren.

Je krijgt twee belangrijke niveaus:

  • Een zandbak. Geen carrier facturering, geen echte wijzerplaten. Gebruik voor ontwikkeling.
  • fnn_live_* productie. Echte gesprekken, echt geld.

Sleutels zijn org-scoped en erven de tarieflimieten + quota van uw plan.

2. Stel omgevingsvariabelen in

export FINN_API_KEY=fnn_test_xxxxxxxxxxxxxxxxxxxx
export FINN_BASE_URL=https://stage-api.hirefinn.ai/v1

Voor de productie, ruilen naar:

export FINN_BASE_URL=https://api.hirefinn.ai/v1

3. Maak uw eerste telefoontje

Noteer je vinnen:

curl $FINN_BASE_URL/finns \
  -H "Authorization: Bearer $FINN_API_KEY"

Verwachte respons:

{
  "data": [
    {
      "id": "fn_abc123",
      "name": "MBBS Callflow",
      "voice_id": "voice_warm_indian_f",
      "language": "en-IN",
      "created_at": "2026-04-12T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "has_more": false
  }
}

Klaar. Je praat met de API.

Basis-URL

EnvironmentURL
Productie
Stage

Alle eindpunten zijn versioned onder /v1. Het breken van veranderingen schip onder een nieuw pad voorvoegsel (/v2, /v3); additieve velden rollen in de huidige versie.

Aanmeldingscontrole

Elk verzoek heeft een API sleutel nodig in de Authorization header:

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

Sleutelbeheer

  • Genereren in Dashboard → Instellingen → Integraties → API Sleutels.
  • Rotate hetzelfde scherm. Oude sleutel ingetrokken onmiddellijk na bevestiging.
    • Revoke * * Instant. Alle verzoeken tijdens de vlucht met behulp van de ingetrokken sleutel falen met 401.
  • Scope De sleutels zijn org-scoped. Gebruik aparte sleutels per omgeving, per dienst.

Beste praktijken

  • Sla sleutels op in omgevingsvariabelen of een geheime manager. Verbind je nooit met bron.
  • Gebruik fnn_test_* voor CI en lokale dev. Productiegegevens mogen nooit een ontwikkelaar laptop zien.
  • Driemaandelijks draaien zelfs zonder een incident.
  • Controle die sleutel gecreëerd welke bron via het created_by_key_id veld op de meeste middelen.

Codevoorbeelden

Hit hetzelfde eindpunt in 3 talen.

cURL

curl https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria — Dental Reminders",
    "voice_id": "voice_warm_indian_f",
    "language": "en-IN",
    "system_prompt": "You are Aria, a friendly...",
    "welcome_message": "Hi, this is Aria from Smile Dental..."
  }'

Knooppunt / TypeScript

import { Finn } from "@finn-voice/sdk";

const finn = new Finn({ apiKey: process.env.FINN_API_KEY });

const agent = await finn.finns.create({
  name: "Aria — Dental Reminders",
  voice_id: "voice_warm_indian_f",
  language: "en-IN",
  system_prompt: "You are Aria, a friendly...",
  welcome_message: "Hi, this is Aria from Smile Dental...",
});

console.log(agent.id);

Python

from finn_voice import Finn

finn = Finn(api_key=os.environ["FINN_API_KEY"])

agent = finn.finns.create(
    name="Aria — Dental Reminders",
    voice_id="voice_warm_indian_f",
    language="en-IN",
    system_prompt="You are Aria, a friendly...",
    welcome_message="Hi, this is Aria from Smile Dental...",
)

print(agent.id)

Responsformaat

Elke succesvolle reactie wraps lading in een consistente envelop.

Enkele middelen

{
  "data": {
    "id": "fn_abc123",
    "name": "MBBS Callflow",
    "created_at": "2026-04-12T10:30:00Z"
  }
}

Lijst

{
  "data": [ /* array of resources */ ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 312,
    "has_more": true
  }
}

Tijdstempels

Alle tijdstempels zijn ISO-8601 UTC (2026-05-22T14:30:00Z).

ID's

Resource ID's zijn vooraf vastgesteld op type voor grep-ability:

Prefix Resource |---|---| | fn_ | Finn (voice agent) | Publiek Inzet Call Telefoonnummer | whk_ | Webhook subscription |

Paginatie

Lijst eindpunten accepteren:

?page=2&per_page=100
  • page defaults to 1.
  • per_page defaults tot 50, max 200.
  • De respons omvat pagination.has_more .

Cursorpaginatie voor high-cardinality eindpunten (oproepen, transcripten):

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Cursor is ondoorschijnend .

Filteren & sorteren

De meeste lijst eindpunten ondersteunen:

?filter[status]=active&filter[call_type]=outbound&sort=-created_at
  • filter[field]=value exacte overeenkomst. Sommige velden accepteren arrays: filter[status]=active,paused.
  • Oplopend. Voorvoegsel met - om af te dalen. Meerdere komma's: sort=-created_at,name.

Idempotentie

Stuur een unieke Idempotency-Key header op POST verzoeken die middelen creëren. Finn dedupliceert opnieuw verzoeken binnen 24 uur.

curl https://api.hirefinn.ai/v1/deployments \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Idempotency-Key: campaign-may-cohort-3-attempt-1" \
  -d '{ "finn_id": "fn_abc123", ... }'

Als je het opnieuw probeert met dezelfde sleutel, krijg je het gecachede antwoord van de eerste oproep en geen dubbele bron aangemaakt.

Fouten

JSON envelop:

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "phone_number_id is required",
    "field": "phone_number_id",
    "request_id": "req_xy12abc"
  }
}

Inclusief request_id in een support ticket .

Statuscodes

Status betekent opnieuw proberen

Onvoldoende fout in de vorm van de lading verkeerd | 401 | API key missing / invalid | No | | 403 | Scoped to different org / plan tier | No | Bron niet gevonden | 409 | Conflict (duplicate name, phone already bound) | No | Afwijzing van bedrijfsregels (naleving, quota) Ja, respect Retry-After Server side, ja, exponentiële backoff

Gemeenschappelijke foutcodes

De code wanneer |---|---| Vereist veld zonder lading Veld aanwezig, maar waarde ongeldig | not_authenticated | Bearer token missing | Token ingetrokken of misvormd Token heeft geen toegang tot deze bron Planlimiet bereikt Te veel verzoeken per seconde Verzoek afgewezen door nalevingsregels Niet genoeg credits om de implementatie te starten

Tarieflimieten

Plan RPS Dagelijks

Starter 5 5.000 Pro 25 50.000 Groei 100 250.000 Onderhandeld Onderhandeld Onderhandeld

Het raken van de limiet geeft 429 terug met headers:

Retry-After: 12
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716391823

Respect Retry-After (seconden) of exponentieel terugtrekken op 5xx.

Middelen in één oogopslag

Beschrijving

Voice agents Audiences Telefoonnummers: /v1/phone-numbers | Deployments | /v1/deployments | Campaigns + inbound bindings | | Calls | /v1/calls | Individual call records | Verkrijgbare TTS-stemmen Abonnementen op evenementen Portemonnee

Webhooks

Abonneren op evenementen. POST'd naar uw URL met HMAC-SHA256 handtekening in X-Finn-Signature.

Register

curl https://api.hirefinn.ai/v1/webhooks \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/finn-webhook",
    "events": ["call.completed", "deployment.completed"],
    "secret": "whsec_yourSecretHere"
  }'

Gebeurtenislading

{
  "id": "evt_2H4abc",
  "type": "call.completed",
  "created_at": "2026-05-22T14:30:00Z",
  "data": {
    "call_id": "cal_xyz789",
    "deployment_id": "dep_xyz789",
    "duration_seconds": 142,
    "outcome": "qualified",
    "recording_url": "https://...",
    "transcript_url": "https://..."
  }
}

Handtekening verifiëren (Node)

import crypto from "crypto";

function verify(req: Request, secret: string): boolean {
  const sig = req.headers.get("X-Finn-Signature") || "";
  const body = req.body;  // raw bytes!
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Agendanotitiecatalogus

Gebeurtenis Brandt wanneer |---|---| Draager pikte de oproep op Oproep beëindigd (om welke reden dan ook) Warm overbrengen naar de mens De campagne begon te bellen Handmatig gepauzeerd Publiek uitgeput | wallet.low_balance | Balance dropped below configured threshold | Succesvolle herlading geregeld | compliance.action_required | Manual review needed |

Betrouwbaarheid

  • Herhalingen op 5xx / timeout: 5 pogingen over ~10 minuten met exponentiële backoff.
  • Order is best-forfort, niet gegarandeerd Gebruik tijdstempels + idempotent handlers.
  • Gebruik de log van het dashboard om mislukte leveringen te herhalen.

SDK's

Officieel:

  • Node / TypeScript
  • ** Python**

Gemeenschap (niet ondersteund):

  • Go, Ruby, PHP

Alle SDK's wrap het REST oppervlak 1:1, behandelen retrieves, en schip types voor elke bron.

OpenAPI-spec

Machineleesbare spec leeft op:

https://api.hirefinn.ai/openapi.json

Gebruik het om klanten te genereren in elke taal, te valideren aanvragen instanties in CI, of importeren in Postman:

Postman → File → Import → Link → https://api.hirefinn.ai/openapi.json

Lokaal testen

Voor lokale webhook ontwikkeling:

# Forward Finn webhooks to your dev machine
ngrok http 3000

# Or use the Finn CLI's built-in tunnel
finn webhooks listen --forward-to http://localhost:3000/webhook

De CLI ook stubs API antwoorden, zodat u integratie tests kunt schrijven zonder een levende sleutel.

Versie

  • Pad versioning Veranderingen breken krijgt een nieuw voorvoegsel.
  • Sunset window .
  • Header opt-in voor beta-functies:
X-Finn-Beta: enable=workflow-canvas-v2

Abonneer je op de Changelog voor de deprecation agenda.

Beperkingen & quota

Grenswaarde |---|---| | Max concurrent deployments | Per plan (5 Starter → unlimited Enterprise) | Max. aantal toeschouwers 5M rijen Max systeemprompt lengte 32K tekens Max webhook URL-lengte 2048 tekens max. grootte van de nuttige lading 1 MB | Recording retention | 90 days default, configurable per plan | Indefinite (met de hand roteren)

Volgende stappen

  1. Build an agent .
  2. Lanceren van een campagne Gebruik de Implementaties doc als recept.
  3. Wire your CRM .
  4. Tune voor de kosten Lees Wallet & AI Credits om het puls-billing model te begrijpen.

Vast? [email protected] .

Was this page helpful?

Still stuck or have feedback?

Email [email protected] or use the chat bubble in the bottom-right corner — it's a Finn that knows the Academy cold.