LIVELead response API · v1

Wire a lead event,
Talkif dials it.

POST /v1/leads → outbound call within seconds.

Send a lead event over webhook or API; Talkif picks the right voice flow, dials within seconds, qualifies intent, posts a structured outcome and fires an outbound webhook back to your stack.

View docs Test a webhook

POST/v1/leads

{

"event": "lead.created",

"source": "web_form",

"phone": "+90••••4218",

"intent": "pricing",

"consent": true,

"call_within": 60

}

202 ACCEPTED

call_id · call_8f2…queued

EYLead · Ece Y.website · pricing form0:02

Talkif AI · 0:02

Hi, this is Talkif calling on behalf of Helena Education. You just left your details on our website — got a moment?

Lead · 0:08

Yes, I want to ask about pricing for the master's programs.

qualifieddemo · 15:30300 ms response

WEBHOOKoutcome.booked

{

"call_id": "call_8f2…",

"outcome": "booked",

"qualified": true,

"booking": {

"slot": "2026-05-26T15:30Z",

"owner": "mehmet@…"

"transcript_url": "…"

}

02 / Quickstart

From webhook to dialed lead in three steps.

Drop one POST in the form-submit handler you already have. Receive a typed webhook back when the call completes. Test keys are free.

Get an API key

Create a project at talkif.ai/docs. Keys scope to a single workspace + a single phone number on the free tier.

POST your first lead

Send the lead event when the form is submitted. Talkif dials within seconds and runs the flow.

Handle the outcome webhook

Subscribe to outcome.*; receive a typed payload (booked / no_answer / disqualified) with transcript + recording URLs.

Average time to first call: under 5 minutes following the docs.

POST /v1/leads

curl -X POST https://api.talkif.ai/v1/leads \
  -H "Authorization: Bearer $TALKIF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "web_form",
    "phone": "+90••••4218",
    "intent": "pricing",
    "consent": true,
    "flow_id": "flow_pricing_v3"
  }'

202 ACCEPTEDcall_id · call_8f2a…avg p95 latency: 41 ms

03 / Pipeline

The voice loop, budgeted.

Every stage is observable, retriable, and has a hard latency budget. Sub-second turn-taking is a system property, not a benchmark slide.

Lead event

webhook

JSON validated, normalized to a typed lead. PII flagged.

Flow router

<5 ms

Match source + campaign + language → flow_id + voice.

Dialer

<60 s

Outbound carrier-grade SIP. Retry on busy/no-answer.

STT

<150 ms

Streaming Whisper-class model with VAD + interruption.

LLM

<450 ms

Slot-filling prompt + function calls (calendar, CRM, etc).

TTS

<120 ms

Streaming neural voice; emotional + pacing controls.

Outcome

webhook

Structured outcome + transcript + recording posted out.

~720 ms

total turn-around p95

3 regions

eu-west · us-east · tr-ist

99.95%

target call uptime

at-least-once

webhook delivery

04 / API + events

Eight endpoints. Eight events.

The full surface is small on purpose — everything is a lead, a call, a flow, or an outcome. Webhooks are typed, signed, and at-least-once.

REST endpointsv1 stable

POST/v1/leadsCreate a lead event; queue an outbound call.

GET/v1/calls/{id}Fetch a call with outcome, transcript URL, audio URL.

POST/v1/flowsCreate or update a flow configuration.

GET/v1/flows/{id}Fetch a flow with its versions.

POST/v1/listsBulk-enqueue leads against a recovery flow.

GET/v1/numbersList provisioned outbound numbers.

POST/v1/handoffsConfigure live human warm-transfer queues.

DELETE/v1/leads/{id}Cancel a queued lead before first dial.

Webhook eventsat-least-once · signed

lead.createdA lead entered the queue. Phone normalized, consent stored.

call.startedTalkif dialed the lead. Includes flow_id + provider call SID.

call.answeredLead picked up. STT/LLM/TTS stream begins.

outcome.bookedBooking slot held in your calendar provider.

outcome.qualifiedLead qualified for callback or handoff.

outcome.no_answerNo pickup. Retry queued per flow policy.

outcome.not_fitLead disqualified. Reason captured in payload.

outcome.wrong_numberNumber invalid. Removed from retry pool.

WEBHOOKoutcome.bookedsigned · hmac-sha256

{
  "event":   "outcome.booked",
  "call_id": "call_8f2ab1c0",
  "lead_id": "lead_91dde222",
  "flow_id": "flow_pricing_v3",
  "outcome": "booked",
  "booking": {
    "slot":  "2026-05-26T15:30:00Z",
    "owner": "mehmet@helena.example",
    "notes": "Fall intake, data track, budget 12k."
  },
  "metrics": {
    "first_dial_ms":   12100,
    "answered_at_ms":  22300,
    "outcome_at_ms":   91450
  },
  "artifacts": {
    "transcript_url": "https://artifacts.talkif.ai/t/...",
    "recording_url":  "https://artifacts.talkif.ai/r/..."
  }
}

05 / Flow as code

Flows are declarative config, not callback spaghetti.

Describe a flow as YAML, version it in git, deploy with the CLI. Branching, retries, and outcome mapping are first-class fields — no nested state machine to reason about.

flows/pricing-v3.yaml$ talkif deploy

id: flow_pricing_v3

match:

source: [web_form, meta_lead_ads]

intent: pricing

language: [tr, en]

call:

within: 60s # dial budget

voice: voice_warm_tr

quiet_hours: 22:00-09:00

qualify:

- need - timing - budget - location

on:

qualified: → book(calendar.mehmet)

no_answer: → retry(15m, max=3) → whatsapp

not_fit: → log("out_of_scope")

06 / Observability

Every call is a trace. Every span is searchable.

Stream call logs, replay transcripts side-by-side with audio, and diff prompt versions. Export OTLP spans straight into your existing observability stack.

trace · call_8f2ab1c07 spans · 91.5 s · status: booked

12:04:11.022lead.receivedok0ms

12:04:11.024flow.matchok2ms

12:04:11.041queue.enqueueok17ms

12:04:23.011dial.startok11.97s

12:04:42.318call.answeredok19.31s

12:05:18.880qualify.donequalified36.56s

12:06:03.412outcome.writebooked44.53s

12:06:03.488webhook.outok76ms

Replay

audio + transcript