Finn Voice API

プログラムによるアクセス — 認証、エンドポイント、ウェブフック。

6 min read

Finn Voice API

FinnAPIは、当社のダッシュボードの使用と同じ表面です。音声エージェントの構築、キャンペーンの立ち上げ、インジェスト分析、プログラム全体.

このガイドは、あなたの最初のライブAPIの呼び出しに〜5分を取得します.

お問い合わせ

クイックスタート(3ステップ)

1. APIのキーをつかんで下さい

ダッシュボード → 設定 → インテグレーション → APIキー → キーを生成します。

2つのキー層を取得します

fnn_test_* — サンドボックス。キャリアの請求、実際のダイヤル無し。開発用途.
fnn_live_* — 生産。実際の呼び出し、実際のお金.

Keys は org-scoped で、プランのレート制限 + quotas を継承します.

2. 環境変数の設定

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

生産のために、交換する:

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

3. 最初の呼び出しを行います

フィンをリスト:

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

期待される応答:

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

お問い合わせ APIに話しています.

お問い合わせ

ベースURL

| 環境 | URL | お問い合わせ | 生産 | | https://api.hirefinn.ai/v1 | | ステージ | https://stage-api.hirefinn.ai/v1 |

すべてのエンドポイントは /v1 でバージョンアップされます。新しいパスプレフィックス(/v2、/v3)の下の変更を破る。添加剤は、現在のバージョンにロールします.

お問い合わせ

認証

Authorization ヘッダの API キーをリクエストする必要があります

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

キー管理

** Dashboard → 設定 → 統合 → API キーで** を生成します.
Rotate — 同じ画面。古いキーはすぐに確認しました.
Revoke — 即刻。 revokedキーを使用してすべての機内リクエストは、401で失敗します.
Scope — キーは org-scoped です。サービスごとの環境ごとの別のキーを使用して下さい.

ベストプラクティス

環境変数または秘密管理者でキーを保存します。ソースにコミットしないでください.
CI およびローカル dev の fnn_test_* を使用して下さい。生産資格情報は、開発者のノートパソコンを見るべきではありません.
事故なく、四半期を回す.
ほとんどのリソースで created_by_key_id フィールドを介してどのリソースを生成したかを監査します.

お問い合わせ

コード例

3つの言語で同じエンドポイントをヒット.

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

ノード/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);

フィードバック

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)

お問い合わせ

応答形式

すべての成功した応答は、一貫した封筒にペイロードをラップします.

単一リソース

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

プロフィール

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

タイムスタンプ

すべてのタイムスタンプはISO-8601 UTC (2026-05-22T14:30:00Z)です.

パスワード

リソースIDは、 grep-ability の型でプレフィックスされます

| プレフィックス | リソース | お問い合わせ | fn_ | Finn | | aud_ | 聴衆 | | dep_ | 展開 | | cal_ | コール | | ph_ | 電話番号 | | whk_ | Webhook サブスクリプション |

お問い合わせ

パジネーション

リストのエンドポイントは受け入れます:

?page=2&per_page=100

page は 1 にデフォルトをします.
per_page は 50 の最高の 200 にデフォルトをします.
応答には、true、増分pageおよび再フェッチ時のpagination.has_moreが含まれます.

高カード化エンドポイント(コール、トランスクリプト):のカーソルのペジネーション

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Cursor は opaque で、次のページをフェッチする as-is を渡します.

お問い合わせ

フィルタリング&ソート

ほとんどのリストエンドポイントのサポート:

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

filter[field]=value — 完全一致。いくつかのフィールドは配列を受け入れる: filter[status]=active,paused.
sort=field — 昇順。降下のための-でプレフィックス。複数のコンマ区切り:sort=-created_at,name.

お問い合わせ

免責事項

リソースを作成する POST リクエストに固有の Idempotency-Key ヘッダを送信します。 Finn は、24 時間以内にリトライされたリクエストを複製します.

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

同じキーを再試行すると、最初の呼び出しからキャッシュされたレスポンスが取得されます。重複したリソースは作成されません.

お問い合わせ

エラー

JSONエンベロープ:

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

どのサポートチケットでもrequest_idを含めてください。ログを通して電話を追跡する方法です.

ステータスコード

| ステータス | 意味 | 再試行 | お問い合わせ | 400 | 検証エラー | ペイロード形状の誤り | ノー | | 401 | API キー欠落 / 無効 | なし | | 403 | 異なる組織・計画段階 | なし | | 404 | 資源が見つかりません | 番号 | | 409 | 紛争(複製名、電話は既に拘束) | いいえ | | 422 | 業務用ルールの拒絶(コンプライアンス・カトラ) | なし | | 429 | レート限定 | はい — Retry-After | | 5xx | サーバー側 | はい — バックオフ |

一般的なエラーコード

お問い合わせ

レート制限

| プラン | RPS | 日刊 | 日刊 | 日刊 | お問い合わせ | 始動機 | 5 | 5,000 | | プロ | 25 | 50,000 | | 成長 | 100 | 250,000 | | 企業 | ネゴティエート | ネゴティエート |

限界を押すと、 429 をヘッダで返します

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

Retry-After(秒)を尊重し、5xxで指数関数的にオフします.

お問い合わせ

一見したリソース

| リソース | エンドポイント | 説明 | お問い合わせ | フィンズ | /v1/finns | ボイスエージェント | | オーディエンス | /v1/audiences | コンタクトリスト | | 電話番号 | /v1/phone-numbers | 保有+レンタルID | | 展開 | /v1/deployments | キャンペーン + インバウンドバインド | | コール | /v1/calls | 個別コールレコード | | 声 | /v1/voices | 利用可能なTTSの声 | | Webhooks | /v1/webhooks | イベント購読 | | ウォレット | /v1/wallet/{orgId} | 残高 + 取引 |

お問い合わせ

Webhooks

イベントの購読 X-Finn-Signatureの HMAC-SHA256 署名で URL にポストします.

会員登録

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

イベントのペイロード

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

署名(ノード)の検証

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

イベントカタログ

信頼性

5xx/タイムアウトのレトリー:指数関数的なバックオフの~10分上の5の試み.
注文は最高の努力であり、保証されていません。 - タイムスタンプ + 重要ハンドラを使用してください.
ダッシュボードのWebhookログを使用して、失敗した配送を再生します.

お問い合わせ

SDKについて

公式:

Node / TypeScript — npm install @finn-voice/sdk — 完全タイプ、再試行組み込み
Python — pip install finn-voice — sync + async クライアント

コミュニティ(サポートされていない):

Go, Ruby, PHP — リポジトリのREADMEへのリンク

すべてのSDKは、REST面1:1をラップし、すべてのリソースのレトリー、および船型を処理します.

お問い合わせ

OpenAPI 仕様

機械で読みやすいスペックは以下に住んでいます:

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

任意の言語でクライアントを生成したり、CI でリクエストボディを検証したり、Postman にインポートしたりするために使用します

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

お問い合わせ

ローカルでのテスト

ローカル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

CLI は API の応答をスタブします。ライブキーなしで統合テストを書くことができます.

お問い合わせ

バージョン

Path versioning — /v1、/v2。変更を解除すると、新しいプレフィックスが表示されます.
Sunset window — 少なくとも 12 ヶ月の非推奨の発表と削除.
ヘッダーオプトインベータ機能:

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

廃止予定のカレンダーの Changelogを変更します.

お問い合わせ

リミット & quotas

お問い合わせ

次のステップ

エージェントをビルド — Finn](/academy/creating-a-finn) 末尾をAPIで作成する.
キャンペーンの実行 — Deployments文書をレシピとして使用してください.
1 CRM をワイヤーで縛って下さい。webhook パターンのための統合を参照してください.
コスト — パルスビルモデルを理解するために、ウォレット&AIクレジットをお読みください.

スタック? [email protected] — エラー応答から request_id を 1 つを持っている場合は含んでいます.

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.

Finn Voice API

クイックスタート(3ステップ)

1. APIのキーをつかんで下さい

2. 環境変数の設定

3. 最初の呼び出しを行います

ベースURL

認証

キー管理

ベストプラクティス

コード例

ログイン

ノード/TypeScript

フィードバック

応答形式

単一リソース

プロフィール

タイムスタンプ

パスワード

パジネーション

フィルタリング&ソート

免責事項

エラー

ステータスコード

一般的なエラーコード

レート制限

一見したリソース

Webhooks

会員登録

イベントのペイロード

署名(ノード)の検証

イベントカタログ

信頼性

SDKについて

OpenAPI 仕様

ローカルでのテスト

バージョン

リミット & quotas

次のステップ