talk;f
All posts
7 min

The Talkif API: Build Voice AI Into Anything

A complete REST API with scoped API keys, 12 resource domains, and every operation programmable — from initiating calls to orchestrating campaigns at scale. Here's what you can build.

Most voice AI platforms give you a dashboard and a prayer. You configure agents through a UI, run campaigns with a button click, and hope the platform does what you expect. When you need to integrate voice into your own product — trigger calls from your CRM, sync transcripts to your data warehouse, orchestrate campaigns from your backend — you hit a wall.

Talkif was built API-first. Every feature in the dashboard is backed by a REST endpoint. If you can click it, you can code it.

Authentication

API keys use the tif_live_ prefix, are SHA-256 hashed at rest (never stored in plaintext), and authenticate via Bearer token:

bashcurl https://api.talkif.ai/api/v1/accounts/{accountId}/calls \
  -H "Authorization: Bearer tif_live_aBcDeFgH..."

Each key gets granular scopes — you control exactly what it can touch:

calls:read        # Read call history, transcripts, recordings
calls:write       # Initiate calls, trigger analysis
flows:read        # List and inspect flows
contacts:*        # Full contact CRUD
campaigns:write   # Create and manage campaigns
analytics:read    # Pull dashboard data
*                 # Full access

12 resource types. 3 permission levels per resource (read, write, *). You can create a key that only reads call transcripts and nothing else — or one that runs your entire integration.

Keys also support IP allowlists (CIDR notation), expiration dates, and usage tracking with per-key request counts, error counts, and unique IP logging. Up to 25 keys per account.

The full key is shown exactly once at creation — store it, because you won't see it again.

Full details: docs.talkif.ai/developer/api-keys

What You Can Build

The API spans every domain in the platform. Here's what matters most for integrations.

Initiate Calls Programmatically

The core action. Trigger an outbound call from your backend — your CRM closes a deal, your scheduler hits a reminder window, your webhook fires.

bashcurl -X POST https://api.talkif.ai/api/v1/accounts/{accountId}/calls \
  -H "Authorization: Bearer tif_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+14155551234",
    "fromNumber": "+14155550100",
    "flowId": "flow_abc123",
    "contactId": "contact_xyz789",
    "metadata": {
      "source": "crm",
      "dealId": "deal_456"
    }
  }'

The response tells you whether the call was initiated immediately (201) or queued (202) based on current capacity:

json// 201 — Initiated
{
  "callId": "call_abc",
  "callSid": "CA...",
  "status": "INITIALIZING"
}
 
// 202 — Queued
{
  "queueId": "queue_def",
  "position": 3,
  "estimatedWaitSeconds": 12
}

Pull Call Details, Transcripts, and Recordings

Every completed call exposes its full history:

bash# Full call details — transcript, analysis, cost, quality metrics, timeline
GET /accounts/{accountId}/calls/{callId}/details
 
# Just the transcript
GET /accounts/{accountId}/calls/{callId}/transcript
 
# Presigned URL for the recording (time-limited)
GET /accounts/{accountId}/calls/{callId}/recording

The detailed endpoint returns everything: per-turn transcripts with latency metrics (STT, LLM, TTS timings per message), AI-generated analysis (summary, sentiment with confidence scores, extracted intents, topics, action items, outcome), call quality data (MOS score, jitter, latency, packet loss), and a full cost breakdown.

bash# Trigger AI analysis on a completed call
POST /accounts/{accountId}/calls/{callId}/analyze

Manage Contacts as a Data Layer

Your contact database is fully CRUD-accessible. Import from CSV or JSON, tag contacts, search by phone number, soft-delete and restore.

bash# Create a contact
POST /accounts/{accountId}/contacts
{
  "firstName": "Sarah",
  "lastName": "Chen",
  "phone": "+14155551234",
  "company": "Acme Corp",
  "timezone": "America/Los_Angeles",
  "tags": ["enterprise", "vip"],
  "customFields": {
    "dealStage": "negotiation",
    "accountManager": "James"
  }
}
 
# Search by phone number (useful for inbound call context)
GET /accounts/{accountId}/contacts/search-by-phone?phone=%2B14155551234
 
# Bulk import
POST /accounts/{accountId}/contacts/import

Contacts feed directly into dynamic prompt resolution — every field you set here becomes available as a Handlebars variable in your flow prompts. When your agent picks up the phone, it already knows who it's talking to.

Run Campaigns at Scale

Campaigns are the orchestration layer for high-volume outbound calling. Create a campaign, attach contacts, start it — and the platform handles scheduling, retries, concurrency, and progress tracking.

bash# Create a campaign
POST /accounts/{accountId}/campaigns
{
  "name": "Q1 Renewal Outreach",
  "flowId": "flow_abc123",
  "fromNumber": "+14155550100",
  "providerId": "provider_twilio_1",
  "scheduleId": "schedule_business_hours"
}
 
# Add contacts
POST /accounts/{accountId}/campaigns/{id}/contacts
{
  "contactIds": ["contact_1", "contact_2", "contact_3"]
}
 
# Or bulk-add by filter
POST /accounts/{accountId}/campaigns/{id}/contacts/bulk
{
  "filter": { "tags": ["renewal-due"] }
}
 
# Start
POST /accounts/{accountId}/campaigns/{id}/start
 
# Pause mid-flight
POST /accounts/{accountId}/campaigns/{id}/pause
 
# Resume
POST /accounts/{accountId}/campaigns/{id}/resume

Campaign contacts get snapshot isolation — their data is frozen at enrollment time. If a contact's record changes mid-campaign, the agent still uses the original data. Consistency across retries, no mid-flight drift.

Flows: Version, Publish, Rollback

Flows are the conversation logic your agents execute. The API gives you full lifecycle control:

bash# List published flows
GET /accounts/{accountId}/flows/published
 
# Create a flow
POST /accounts/{accountId}/flows
 
# Validate before publishing
POST /accounts/{accountId}/flows/{flowId}/validate
 
# Publish (creates a new version)
POST /accounts/{accountId}/flows/{flowId}/publish
 
# List versions
GET /accounts/{accountId}/flows/{flowId}/versions
 
# Rollback to a previous version
POST /accounts/{accountId}/flows/{flowId}/rollback

Flows support semantic versioning. Validate before publishing — the API checks for broken node references, missing configurations, and unreachable nodes. Duplicate flows for A/B testing. Roll back to any previous version if something goes wrong.

Phone Numbers: Purchase, Configure, Connect

Manage your phone number inventory programmatically. Search available numbers by country and region, purchase them, connect them to flows for inbound handling.

bash# List available numbers
GET /accounts/{accountId}/phone/available?country=US&region=CA
 
# Purchase
POST /accounts/{accountId}/phone/purchase
 
# Connect a flow to handle inbound calls
POST /accounts/{accountId}/phone/numbers/{id}/connect-flow
{
  "flowId": "flow_support_intake"
}

Talkif supports three provider types: managed Twilio (simplest), Bring Your Own Carrier (use your existing Twilio account), and SIP (connect any SIP trunk). Full BYOC documentation: docs.talkif.ai/phone-numbers/byoc

Analytics: Build Your Own Dashboards

Pull aggregated metrics for custom reporting, monitoring, or feeding into your BI tools:

bash# Call volume and completion rates
GET /accounts/{accountId}/analytics/calls-summary?from=2026-03-01&to=2026-03-11
 
# Cost trends over time (chart-ready data)
GET /accounts/{accountId}/analytics/cost-trend
 
# Success rate by hour and day of week (heatmap data)
GET /accounts/{accountId}/analytics/success-rate-heatmap
 
# Per-flow performance comparison
GET /accounts/{accountId}/analytics/flow-performance
 
# Call outcome distribution
GET /accounts/{accountId}/analytics/call-outcomes

Every analytics endpoint supports date ranges and returns structured data ready for visualization.

Prompt Templates

Manage reusable prompt templates via API — create, resolve with variables, or let AI generate them:

bash# Create a template
POST /accounts/{accountId}/prompt-templates
{
  "name": "Appointment Reminder",
  "content": "You are calling {{default contact.firstName \"there\"}} to confirm their appointment..."
}
 
# Resolve a template with actual data
POST /accounts/{accountId}/prompt-templates/{id}/resolve
 
# AI-generate a template from a description
POST /accounts/{accountId}/prompt-templates/generate
{
  "description": "A friendly appointment reminder that checks VIP status"
}
 
# List available template variables
GET /accounts/{accountId}/template-variables

Do Not Call Compliance

Built-in DNC list management:

bash# Check before calling
POST /accounts/{accountId}/dnc/check
{ "phoneNumber": "+14155551234" }
 
# Add to DNC list
POST /accounts/{accountId}/dnc
{ "phoneNumber": "+14155551234", "reason": "customer_request" }
 
# Bulk import
POST /accounts/{accountId}/dnc/bulk

The platform automatically checks DNC lists before placing outbound calls. Sync your existing DNC lists into Talkif and keep them current.

Schedules

Define when calls can be placed — business hours, timezone-aware windows, blackout periods:

bashPOST /accounts/{accountId}/schedules
{
  "name": "US Business Hours",
  "timezone": "America/New_York",
  "windows": [
    { "day": "monday", "start": "09:00", "end": "17:00" },
    { "day": "tuesday", "start": "09:00", "end": "17:00" }
  ]
}

Attach schedules to campaigns. Pause and resume on the fly.

AI Model Discovery

Query available AI providers and models:

bash# List all LLM providers
GET /accounts/{accountId}/models/llm
 
# List TTS voices
GET /accounts/{accountId}/models/tts/voices
 
# Preview a Cartesia voice before committing
POST /accounts/{accountId}/models/cartesia/preview

Talkif supports OpenAI, Anthropic, Azure OpenAI, Google, and Grok for LLM; ElevenLabs and Cartesia for TTS; Deepgram, AssemblyAI, Soniox, Cartesia, and ElevenLabs for STT. Provider selection is per-flow — mix and match based on your latency, cost, and quality requirements.

How It Fits Together

Your Infrastructure Talkif API sync contacts trigger call start campaign poll transcripts pull metrics version control CRM / Backend Data Warehouse Internal Dashboard /calls /contacts /campaigns /analytics /flows

Your backend is the orchestrator. Talkif is the voice execution layer. The API is the boundary between them — clean, scoped, and stateless.

Error Handling

Every error follows a consistent structure:

json{
  "code": "validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "requestId": "01234567-89ab-cdef-0123-456789abcdef",
  "errors": [
    {
      "field": "toNumber",
      "code": "invalid_format",
      "message": "Phone number must be in E.164 format"
    }
  ]
}

Rate limit errors include meta.retryAfterSecs. The requestId is your correlation key for support.

Rate limits: 1000-request burst, then 60 requests per minute sustained. Auth endpoints have tighter limits to prevent abuse.

Pagination

All list endpoints use offset-based pagination:

bashGET /accounts/{accountId}/calls/history?limit=50&offset=100
json{
  "calls": [...],
  "meta": {
    "total": 2847,
    "limit": 50,
    "offset": 100
  }
}

Default limit: 20. Maximum: 100.

Integration Patterns

CRM-triggered calls. Deal stage changes in Salesforce -> webhook -> your middleware -> POST /calls. The contact's CRM data flows through to the agent's prompt via dynamic templates.

Post-call pipelines. Poll completed calls -> fetch transcript and analysis -> push to your data warehouse. Every call becomes structured data in your system of record.

Automated campaign orchestration. Your scheduling system decides when to run campaigns based on business logic Talkif doesn't need to know about. Create campaigns, add contacts by filter, start them — all via API.

Compliance automation. Sync your DNC lists nightly. Pull call recordings for audit. Export analytics for regulatory reporting.

Custom analytics. Pull heatmap data, cost trends, and flow performance metrics into Grafana, Looker, or your own dashboards. The analytics endpoints return chart-ready data structures.

CI/CD for conversation flows. Version flows in your deployment pipeline. Validate before publish, rollback on failure. Treat conversation design like code — because it is.

API Reference

The full OpenAPI 3.1 spec is available at:

https://api.talkif.ai/api/v1/openapi.json

Interactive reference with request/response schemas and code generation: docs.talkif.ai/reference

Every endpoint, every field, every enum value — documented and generated from the source code. No drift between docs and reality.