Finn setup and results

Beta. The setup endpoints on this page need Finn editing by API switched on for your organization. While it is off, each of them answers 404. Ask Finn support to turn it on. The results endpoints at the end work for every organization.

Overview

Finns covers creating, reading and updating a Finn. This page covers the rest of a Finn's setup: drafting one with AI, its call flow, variables, handbook and speech settings, copies and share links. It also covers the results you read back after calls.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication.

Scopes: reads need finn:read and writes need finn:write. An org API key may use voice:read and voice:write instead. See scopes.

Responses use the { "success": true, "data": ... } envelope, like the other voice endpoints.

Rules for edits

Edits change a draft Finn only. A live Finn gets 403 finn_not_draft.
A member's token (OAuth or a personal MCP key) may edit only drafts that member created. Others get 403 finn_not_yours.
Nothing here makes a Finn live. A person does that in Finn, or you deploy it (see deployments).
Writes share a limit of 120 per minute per key. Reads share 300 per minute per key.

Draft and copy

Method	Path	What it does
`POST`	`/finns/generate`	Turn a short `brief` into a full draft Finn: name, persona, opening line, prompt and post-call fields. Optional `voice` and `language`. 10 per minute per key.
`POST`	`/finns/{finn_id}/duplicate`	A new draft copy of any Finn in your organization. Without `name` it is called "<name> (copy)".
`PATCH`	`/finns/{finn_id}/draft`	The same body and answer as `PATCH /finns/{finn_id}`, but refused unless the Finn is a draft.

Settings

Method	Path	What it does
`GET`	`/finns/{finn_id}/settings`	What `GET /finns/{finn_id}` leaves out: handbook, speech settings, call flow summary, task settings and knowledge documents.
`PATCH`	`/finns/{finn_id}/handbook`	Change handbook switches. Send only the ones to change, for example `{"handbook": {"accuracy": {"natoPhonetic": true}}}`.
`PATCH`	`/finns/{finn_id}/speech_settings`	Change speech settings, for example `{"speech_settings": {"ttsSpeed": 1.1}}`. `null` or `""` removes a setting. An unknown setting or a value out of range gets `400`.
`GET`	`/finns/{finn_id}/variables`	Placeholders in the prompt fields, the placeholder to CSV column mapping, and the post-call fields.
`PATCH`	`/finns/{finn_id}/variables`	Change the mapping (`set_mapping`, `remove_mapping`), turn it on or off (`mapping_enabled`), or replace `post_call_fields`.

See variables and post-call analysis for what these settings do on a call.

Call flow

Method	Path	What it does
`GET`	`/finns/{finn_id}/flow`	The call flow canvas as nodes and edges, and whether it runs instead of the prompt.
`POST`	`/finns/{finn_id}/flow/enable`	The Finn follows its call flow instead of its prompt. `409 flow_empty` when there is no flow.
`POST`	`/finns/{finn_id}/flow/disable`	The Finn runs on its prompt. The canvas is kept.

To change the canvas itself, send call_flow to PATCH /finns/{finn_id}. See call flows.

Method	Path	What it does
`GET`	`/finns/{finn_id}/share_link`	The latest share link, or `null`. A share link is a public page where anyone can talk to the Finn.
`POST`	`/finns/{finn_id}/share_link`	Returns the latest link, or makes one (`201`). A link that was turned off stays off.

Calls on a share link use your organization's credit.

Results

Method	Path	Scope	What it does
`GET`	`/finns/{finn_id}/stats`	`finn:read`	Totals only: calls, answered, successful, voicemail, minutes and cost, by status, direction and sentiment.
`GET`	`/finns/{finn_id}/outcomes`	`finn:read`	Post-call answers summed up per field: counts per choice and number ranges. A free-text answer shows only when it came up at least 3 times, with digits masked.
`GET`	`/finns/{finn_id}/post_call_analysis`	`voice:read`	Each post-call question with how its answers are spread across calls. Works without Finn editing.
`GET`	`/deployments/{id}/analytics`	`voice:read`	One deployment's totals: calls placed and answered, rates, durations and how calls ended. Works without Finn editing.

Stats, outcomes and post-call analysis take optional from and to to narrow the window. Deployment analytics covers the whole deployment. It is computed when you ask, so it is right for a deployment that is still running. Per-call answers are on GET /calls/{call_uuid} (see calls).

Example: draft a Finn with AI

curl -X POST https://api.hirefinn.ai/api/v1/finns/generate \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Call people who asked for a dental check-up quote. Confirm the clinic they chose and book a slot.",
    "language": "en"
  }'

The answer is 201 with the new draft (some fields left out):

{
  "success": true,
  "data": {
    "id": "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    "name": "Check-up Booking",
    "status": "draft",
    "language": "en",
    "begin_message": "Hi, this is Finn from the clinic. Is now a good time?",
    "post_call_analysis": []
  }
}

Read it back, change what you need with PATCH /finns/{finn_id}/draft, and try it on a test call before you deploy it. Without a voice, the AI picks one your organization can use.

Then read deployment results:

curl https://api.hirefinn.ai/api/v1/deployments/6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03/analytics \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": {
    "deployment_id": "6b1f0c2e-3d4a-4f5b-9c8d-2e7a1b9f4c03",
    "calls": { "total": 120, "answered": 86, "completed": 80, "unanswered": 28, "voicemail": 6, "successful": 54 },
    "rates": { "answer_rate_percent": 71.67, "success_rate_percent": 45, "voicemail_rate_percent": 5 },
    "duration": { "total_seconds": 7420, "average_seconds": 86 }
  }
}