API Finn Voice

Finn Voice API

Le Finn API est la même surface que notre tableau de bord. Construisez des agents vocaux, lancez des campagnes, ingérez l'analyse, tous programmatiques.

Ce guide vous amène à votre premier appel en direct API en ~5 minutes.

Démarrage rapide (3 étapes)

1. Saisissez une touche API

Tableau de bord → Paramètres → Intégrations → API Clés → Générer la clé.

Vous obtiendrez deux niveaux clés:

• fnn_test_* — bac à sable. Pas de facturation, pas de vrais cadrans. Utilisation pour le développement.
• fnn_live_* — production. De vrais appels, de l'argent.

Les clés sont org-scoped et héritent des limites de taux de votre régime + quotas.

2. Définir les variables d'environnement

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

Pour la production, échanger avec:

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

3. Faites votre premier appel

Énumérez vos nageoires :

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

Réponse attendue :

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

C'est fait. Vous parlez au API.

URL de base

Environnement URL

• Oui Production Étape

Tous les paramètres sont présentés sous /v1. Breaking changes ship under a new path prefix (/v2, /v3); les champs additifs roulent dans la version actuelle.

Authentification

Chaque requête nécessite une clé API dans l'en-tête Authorization:

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

Gestion des clés

• Générer dans le tableau de bord → Paramètres → Intégrations → API Clés.
• Rotat — même écran. Vieille clé révoquée immédiatement sur confirmation.
• Révélation — instant. Toutes les requêtes en vol utilisant la clé révoquée échouent avec 401.
• Portée — les clés sont org-scoped. Utilisez des clés séparées par environnement, par service.

Meilleures pratiques

• Stockez les clés dans des variables d'environnement ou dans un gestionnaire secret. Ne jamais s'engager à la source.
• Utilisez fnn_test_* pour CI et dev local. Les références de production ne devraient jamais voir un ordinateur portable développeur.
• Rotation trimestrielle même sans incident.
• Audit quelle clé a créé quelle ressource via le champ created_by_key_id sur la plupart des ressources.

Exemples de codes

Appuyez sur le même paramètre en 3 langues.

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

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

Format de réponse

Chaque réponse réussie enveloppe la charge utile dans une enveloppe cohérente.

Une seule ressource

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

Liste

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

Timbres

Tous les horodatages sont ISO-8601 UTC (2026-05-22T14:30:00Z).

Numéro d'identification

Les ID de ressources sont préfixés par type pour la grep-ability:

Préfixe Ressource

• Oui (agent de voix) 2 Audience Déploiement Appel Numéro de téléphone Webhook Webhook abonnement

Pagination

Lister les paramètres acceptés:

?page=2&per_page=100

• page par défaut à 1.
• per_page par défaut à 50, max 200.
• La réponse comprend pagination.has_more — quand true, incrément page et re-fetch.

Pagination du curseur pour les paramètres de cardinalité élevée (appels, transcriptions):

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Curseur est opaque — passez-le comme-est pour récupérer la page suivante.

Filtrage & tri

La plupart des paramètres de la liste prennent en charge:

?filter[status]=active&filter[call_type]=outbound&sort=-created_at

• filter[field]=value — correspondance exacte. Certains champs acceptent les tableaux : filter[status]=active,paused.
• sort=field — ascendant. Préfixe avec - pour descendre. Séparer plusieurs virgules : sort=-created_at,name.

Idempotency

Envoyer un en-tête unique Idempotency-Key sur les requêtes POST qui créent des ressources. Finn dédouble les demandes rejugées dans les 24 heures.

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

Si vous réessayez avec la même clé, vous obtenez la réponse mise en cache du premier appel — aucune ressource dupliquée créée.

Erreurs

Enveloppe JSON:

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

Inclure request_id dans n'importe quel ticket de support — c'est comment nous traçons votre appel dans nos journaux.

Codes d'état

Sensation de réessayer

• Oui Erreur de validation — forme de charge utile incorrecte API touche manquante / invalide 403=Étendu à différents niveaux d'org/plan 404=Resource non trouvée Le conflit (dupliquer le nom, téléphone déjà lié) 422=Rejection de la règle d'affaires (respect, quota) Taux limité Oui — respect 5xx=QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ

Codes d'erreur communs

Code à quel moment

• Oui missing_field= Champ obligatoire absent de la charge utile= invalid_field=0 Champ présent mais valeur invalide

# # # # # # # # # # # # # # # # #

# # # # # # # # # # # #

Le token n'a pas accès à cette ressource quota_exceeded Trop de demandes par seconde Demande rejetée par les règles de conformité wallet_insufficient=Pas assez de crédits pour lancer le déploiement

Limites tarifaires

Plan de travail quotidien

• Oui Démarreur Pour 25 $ 50 000 $ Croissance Entreprise Négociée Négociée

Affichage de la limite renvoie 429 avec des en-têtes & #160;:

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

Respectez Retry-After (secondes) ou reculez exponentiellement sur 5xx.

Les ressources en bref

Description de la ressource

• Oui Finlandais /v1/finns Auditoires /v1/audiences Numéros de téléphone /v1/phone-numbers="Propriété + DID loué" Déploiements /v1/deployments= Campagnes + liaisons entrantes Appels d'appel individuels TTS voix disponibles Abonnements à l'événement Portefeuille /v1/wallet/{orgId}2 Solde + transactions

Webhooks

Abonnez-vous aux événements. POST'd à votre URL avec la signature HMAC-SHA256 dans X-Finn-Signature.

Registre

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

Charge utile de l'événement

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

Signature de vérification (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));
}

Catalogue des événements

Événement

• Oui Le transporteur a pris l'appel call.completed= Appel terminé (toute raison)= call.transferred=Le transfert chaud vers l'humain La campagne a commencé à composer Transcription manuelle 2 Auditoire épuisé wallet.low_balance=Le solde est tombé sous le seuil configuré Réussite de la recharge 2 Révision manuelle nécessaire

Fiabilité

• Retries on 5xx / timeout: 5 tentatives sur ~10 minutes avec retour exponentiel.
• La commande est le meilleur effort, pas garanti — utilisez des horodatages + des gestionnaires idémpotents.
• Utilisez le journal webhook du tableau de bord pour rejouer les livraisons ratées.

SDKs

Fonctionnaire:

• Node / TypeScript — npm install @finn-voice/sdk — entièrement dactylographié, réessayer intégré
• Python — pip install finn-voice — synchronisation + clients async

Communauté (non soutenue):

• Go, Ruby, PHP — liens dans le repo README

Tous les SDK enveloppent la surface REST 1:1, manipulent les rétries et les types de navires pour chaque ressource.

Spec OpenAPI

Spec lisible par machine vit à:

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

Utilisez-le pour générer des clients dans n'importe quelle langue, valider des organismes de demande dans CI ou importer dans Postman:

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

Essais locaux

Pour le développement local du webhook :

# 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

Le CLI tient aussi des réponses API afin que vous puissiez écrire des tests d'intégration sans clé en direct.

Versionnement

• Version imprimée — /v1, /v2. Briser les changements obtenir un nouveau préfixe.
• Fenêtre d'extinction — au moins 12 mois entre l'annonce de déprécation et la suppression.
• Opt-in pour les caractéristiques bêta:

X-Finn-Beta: enable=workflow-canvas-v2

Inscrivez-vous au Changelog pour le calendrier de déprécation.

Limites et quotas

Valeur

• Oui Nombre maximum de déploiements simultanés par plan (5 démarrage → entreprise illimitée) Taille maximale du public Longueur maximale de l'invite système Longueur maximale de l'URL du webhook Webhook charge utile max taille Enregistrement de la rétention de 90 jours par défaut, configurable par plan API durée de vie des clés

Prochaines étapes

1. Construisez un agent — essayez le Création d'un Finn passant de bout en bout via API.
2. ** Lancer une campagne** — utiliser le Deployments doc comme recette.
3. Essayez votre CRM — voir Intégréations pour les modèles de webhook.
4. Tune pour coût — lire Wallet & AI Credits pour comprendre le modèle de facturation d'impulsions.

Coincé ? [email protected] — inclure le request_id de la réponse d'erreur si vous en avez une.