Calls

Beta. Place-a-call and retrieve-a-call are live and documented as shipped. There is no endpoint to list or cancel calls.

Overview

The Calls API places one outbound call and reads the record of a call. A call is tied to a Finn (the agent), which supplies the voice, the prompt, the language and the transfer number. You pass the Finn's ID and a destination number. Everything else comes from that Finn's saved configuration.

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

The Finn must belong to the organization that issued your API key. A Finn in another organization returns 404 finn_not_found, the same response as a Finn that does not exist, so the endpoint cannot be used to discover which IDs are in use elsewhere.

To call a list of contacts, create an outbound deployment with api-deployments instead of looping this endpoint. Single calls are meant for event-driven cases such as a form submission, a CRM webhook or a support escalation.

Endpoints

Place a call

POST /calls

curl -X POST https://api.hirefinn.ai/api/v1/calls \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "finn_id": "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    "to_number": "4155550142",
    "country_code": "1"
  }'

Any other field in the body, including metadata, is ignored.

Which Finn settings apply. The call uses the Finn's voice, language, begin_message, identity_text, system_prompt (added after identity_text), style_guardrails, response_guidelines and handoff_number. It does not use max_call_duration_minutes, idle_reminder_message, idle_reminder_after_seconds or end_call_on_silence_seconds: those apply only to calls from deployments, and a single call runs with Finn's defaults for them. See Call settings and which calls use them.

Caller ID. Every call placed with this endpoint comes from the same Finn-owned Indian number (+91), whatever the destination country. You can't choose or change it, and you can't place the call from a number you rented. Outside India, the person you call sees an international Indian number rather than a local one, which can lower answer rates. To show a local caller ID, rent a number in that country (api-phone-numbers) and call through an outbound deployment that uses it (api-deployments).

There is no idempotency key. A retried POST places a second real call, so retry only when you know the first request did not reach the server.

The response is 202 Accepted once Finn has accepted the call for dialing:

{
  "success": true,
  "data": {
    "call_uuid": "b7e3c9a2-4d1f-4e8b-9a6c-2f5d8e1b3c70",
    "finn_id": "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    "to_number": "4155550142",
    "status": "initiated"
  }
}

to_number echoes what you sent, trimmed. call_uuid is the ID for every later lookup.

Errors

Error bodies have the shape { "error": "...", "message": "..." }; internal_error has no message. See api-errors.

Retrieve a call

GET /calls/{call_uuid}

Returns any call in your organization: calls placed with POST /calls, calls dialed by deployments, and inbound calls.

curl https://api.hirefinn.ai/api/v1/calls/b7e3c9a2-4d1f-4e8b-9a6c-2f5d8e1b3c70 \
  -H "Authorization: Bearer $FINN_API_KEY"

{
  "success": true,
  "data": {
    "call_uuid": "b7e3c9a2-4d1f-4e8b-9a6c-2f5d8e1b3c70",
    "finn_id": "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    "deployment_id": null,
    "status": "completed",
    "disconnect_reason": "hangup",
    "direction": "outbound",
    "from_number": "+918045550199",
    "to_number": "+14155550142",
    "duration_seconds": 97,
    "user_sentiment": "positive",
    "call_successful": true,
    "created_at": "2026-09-16T09:14:02.000Z",
    "updated_at": "2026-09-16T09:15:41.000Z",
    "recording_url": "https://storage.example.com/recordings/b7e3c9a2-4d1f-4e8b-9a6c-2f5d8e1b3c70.wav?sig=...",
    "billing": {
      "credits_charged": 2,
      "price_per_credit": 7,
      "currency": "INR",
      "estimated_cost": 14
    },
    "analysis": [
      {
        "question_name": "interested",
        "question_type": "Yes/No",
        "answer": "Yes",
        "needs_review": false,
        "reasoning": "Caller asked for a follow-up call on Tuesday.",
        "extracted_at": "2026-09-16T09:16:10.000Z"
      }
    ]
  }
}

The call object

billing is an estimate computed when you read the call. It is ceil(duration_seconds / 60) credits at your organization's current price_per_credit, so a 10-second call shows one credit. It does not apply plan multipliers or unanswered-call charges, and nothing is charged by reading it. The wallet ledger is the record of what was actually debited: see GET /wallet/transactions in api-wallet.

Each analysis item has question_name, question_type, answer, needs_review (boolean), reasoning and extracted_at. The questions are the Finn's post_call_analysis configuration; see api-finns. Analysis runs after the call ends, so an empty array on a call that has just finished is expected.

The call record isn't created by POST /calls itself. It appears after the call ends, usually within about 5 minutes. Until then, a GET returns 404 call_not_found. Retry with a backoff, or wait for the call.completed webhook.

Errors

Call status

Status values come from the carrier and from how the call went, so this is the common set, not a closed enum. Compare case-insensitively and handle unknown values.

Rate limits

Limits are counted per API key, not per IP. Over the limit returns 429 with {"error": "rate_limited", "message": "..."}, a Retry-After header, and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers on every response. See api-rate-limits.

TypeScript example

const res = await fetch("https://api.hirefinn.ai/api/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FINN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    finn_id: "8f14e45f-ceea-467a-9f6a-1c0e5b2a77d1",
    to_number: "+14155550142",
    country_code: "1",
  }),
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${res.status} ${body.error}: ${body.message ?? ""}`);
}

console.log(body.data.call_uuid, body.data.status);

Getting results

Pull a finished call with GET /calls/{call_uuid}, or register a webhook endpoint and receive a signed call.completed event after the call ends, usually within about 5 minutes. Calls placed with POST /calls and calls nobody answered get the event too. See api-webhooks to register an endpoint, webhook-post-call for the payload and webhook-security to verify signatures.

Not available

There is no endpoint to list calls or cancel a call, and metadata is not stored or returned. For call history in bulk, use the export in the dashboard.