Skip to main content

Finn Voice API

Programmatisk åtkomst — autentisering, endpoints, webhooks.

8 min read

Finn Voice API

FinnAPI är samma yta som vår instrumentpanel använder. Bygg röstagenter, starta kampanjer, inta analyser - allt programmatiskt.

Den här guiden får dig till din första live API samtal i ~ 5 minuter.

Quickstart (3 steg)

1. Ta en API nyckel

Dashboard → Inställningar → Integrationer → API Keys → Generera nyckel.

Du får två nyckelnivåer:

  • fnn_test_* - Sandbox. Ingen operatör fakturering, inga riktiga ratt. Använd för utveckling.
  • fnn_live_* - produktion. Riktiga samtal, riktiga pengar.

Nycklar är org-scoped och ärver din plans kursgränser + kvoter.

2. sätt miljövariabler

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

För produktion, byta till:

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

Gör ditt första samtal

Lista ditt finns:

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

Förväntat svar:

{
  "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
  }
}

Done. Du pratar med API.

Base URL

Miljö | URL | |-------- | Produktion | https://api.hirefinn.ai/v1 | | Steg | https://stage-api.hirefinn.ai/v1 |

Alla endpoints är versionerade under /v1. Breaking ändrar fartyg under en ny vägprefix (/v2, /v3); additiva fält rulla in i den aktuella versionen.

Autentisering

Varje begäran behöver en API-nyckel i Authorization-rubriken:

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

Nyckelhantering

  • Generera i Dashboard → Inställningar → Integrationer → API Keys.
  • *Rotate - samma skärm. Gamla nyckel återkallas omedelbart på bekräftelse.
  • ** Återkalla** – ögonblick. Alla begäranden om flygning med hjälp av den återkallade nyckeln misslyckas med 401.
  • Scope - nycklar är org-scoped. Använd separata nycklar per miljö, per service.

Bästa praxis

  • Lagra nycklar i miljövariabler eller en hemlig chef. Begå aldrig till källa.
  • Använd fnn_test_* för CI och lokal dev. Produktionsuppgifter bör aldrig se en utvecklare laptop.
  • Rotera kvartalsvis även utan en incident.
  • Granska vilken nyckel som skapats som resurs via created_by_key_id fältet på de flesta resurser.

Kodexempel

Hit samma slutpunkt på tre språk.

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..."
  }'

Nod / 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)

Svarsformat

Varje framgångsrikt svar slår nyttolast i ett konsekvent kuvert.

Enkel resurs

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

Lista List

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

Timestamps

Alla tidsstämplar är ISO-8601 UTC (2026-05-22T14:30:00Z).

IDs

Resurs-ID prefixeras efter typ för grep-ability:

Prefix | Resurs | |-------- | fn_ | Finn (röstagent) | | aud_ | Audience | | dep_ | Utplacering | | cal_ | Ring | | ph_ | Telefonnummer | | whk_ | Webhook abonnemang |

Paginering

List endpoints accepterar:

?page=2&per_page=100
  • page standarder till 1.
  • per_page standarder till 50, max 200.
  • Response inkluderar pagination.has_more - när true, steg page och återhämtning.

Cursor paginering för hög kardinalitets endpoints (samtal, utskrifter):

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Cursor är ogenomskinlig - passera den tillbaka som-är att hämta nästa sida.

Filtrera & sortering

De flesta list endpoints support:

?filter[status]=active&filter[call_type]=outbound&sort=-created_at
  • filter[field]=value - exakt match. Vissa fält accepterar matriser: filter[status]=active,paused.
  • sort=field - uppstigning. Prefix med - för nedstigning. Koma-separat multipel: sort=-created_at,name.

Idempotens

Skicka en unik Idempotency-Key rubrik på POST förfrågningar som skapar resurser. Finn deduplicerar återkallade förfrågningar inom 24 timmar.

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", ... }'

Om du retry med samma nyckel får du det cachade svaret från det första samtalet - ingen dubblettresurs skapad.

Fel

JSON kuvert:

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

Inkludera request_id i någon supportbiljett - det är så vi spårar ditt samtal genom våra loggar.

Statuskoder

Status | Betydelse | Retry |---------- | 400 | Validationsfel - nyttolast form fel | Nej | | 401 | API nyckel saknas/ogiltig | Nej | | 403 | Avslutad till olika org / plannivå | Nej | | 404 | Resurs som inte finns | Nej | | 409 | Konflikt (duplicera namn, telefon redan bunden) | Nej | | 422 | Business-rule refuse (överensstämmelse, kvot) | Nej | | 429 | Rate limited | Yes - Respekt Retry-After | | 5xx | Server sida | Ja - exponentiell backoff |

Vanliga felkoder

| Kod | När | |-------- | missing_field | Obligatoriskt fält frånvarande från nyttolast | | invalid_field | Fältet närvarande men värdet ogiltigt | | not_authenticated | Bärare token saknas | | invalid_token | Token återkallad eller missbildad | | forbidden_scope | Token har inte tillgång till denna resurs | | quota_exceeded | Plan limit hit | | rate_limited | För många förfrågningar per sekund | | compliance_block | Begäran som avvisas genom reglerna om efterlevnad | wallet_insufficient | Inte tillräckligt med krediter för att starta utplacering |

Rate limits

Plan | RPS | Daglig | |---------- Starter | 5 | 5 000 | Pro | 25 | 50 000 | Tillväxt | 100 | 250.000 | Enterprise | Förhandlat | Förhandlat |

Att slå gränsen returnerar 429 med rubriker:

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

Respekt Retry-After (andra) eller tillbaka exponentiellt på 5xx.

Resurser vid en blick

| Resurs | Slutpunkt | Beskrivning | |---------- finländare | /v1/finns | Voice agents | | Publikationer | /v1/audiences | Kontaktlistor | | Telefonnummer | /v1/phone-numbers | Ägda + hyrda DID | | Utplaceringar | /v1/deployments | Kampanjer + inkommande bindningar | | Samtal | /v1/calls | individuella samtalsregister | | Röster | /v1/voices | Tillgängliga TTS-röster | | Webhooks | /v1/webhooks | Evenemangsabonnemang | Plånbok | /v1/wallet/{orgId} | Balans + transaktioner |

Webhooks

Prenumerera på händelser. POST skulle till din URL med HMAC-SHA256 signatur i X-Finn-Signature.

Registrera

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"
  }'

Event payload

{
  "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://..."
  }
}

Verifiera signatur (nod)

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));
}

Event katalog

Event | Eldar när | |-------- | call.started | Carrier plockade upp uppmaningen | | call.completed | Call avslutades (någon anledning) | | call.transferred | Varm överföring till människa | | deployment.started | Kampanjen började ringa | | deployment.paused | Manuellt pausad | | deployment.completed | Audience utmattad | | wallet.low_balance | Balans sjönk under konfigurerad tröskel | wallet.topup_complete | Framgångsrik laddning avgjorde | | compliance.action_required | Manuell översyn behövs |

Tillförlitlighet

  • Retries on 5xx / timeout: 5 försök över ~ 10 minuter med exponentiell backoff.
  • Beställningen är bäst, inte garanterad - använd tidsstämplar + idempotent hanterare.
  • Använd instrumentpanelens webhook-logg för att spela misslyckade leveranser.

SDKs

Officiell:

  • Nod / TypeScript - npm install @finn-voice/sdk - fullt skriven, retry inbyggd
  • Python – pip install finn-voice – synkronisera + asynkunder

Gemenskap (som inte stöds):

  • GoRuby****** – länkar i repo README

Alla SDKs linda REST-ytan 1:1, hantera retries och skeppstyper för varje resurs.

OpenAPI spec

Maskinläsbara spec lever på:

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

Använd den för att skapa kunder på något språk, validera förfrågningsorgan i CI eller importera till Postman:

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

Testa lokalt

För lokal webhook utveckling:

# 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

CLI stubbar också API svar så att du kan skriva integrationstest utan en levande nyckel.

Versioning

  • Path versioning – /v1, /v2. Breaking förändringar får ett nytt prefix.
  • Sunset window - minst 12 månader mellan avskrivningar och borttagning.
  • Header opt-in för beta-funktioner:
X-Finn-Beta: enable=workflow-canvas-v2

Prenumerera på Changelog för avskrivningskalendern.

Begränsningar och kvoter

| Begränsning | Värde | |-------- Max samtidiga utplaceringar | Per plan (5 Starter → obegränsad Enterprise) | Max publik storlek | 5M rader | Max system snabb längd | 32K tecken | Max webhook URL längd | 2048 tecken | | Webhook nyttolast max storlek | 1 MB | | Inspelning lagring | 90 dagar standard, konfigurerbar per plan | | API nyckelliv | Obestämd (roterar manuellt) |

Nästa steg

  1. Bygga en agent -- prova Skapa en Finn genomgående end-to-end via API.
  2. Låt en kampanj – använd Deployments doc som recept.
  3. ** Om din CRM********************************************************************************************************************************************************************************************************************************************************.
  4. Tune for cost – läs Wallet & AI Credits] för att förstå pulsbillingsmodellen.

Stuck? [email protected] - inkludera request_id från felsvaret om du har en.

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.