API v1.2 · Production Live

Paisan Voice AI Developer API

Programmatically initiate calls, inject real-time context, orchestrate inbound AI phone agents, and consume emotion-aware conversation outcomes directly into your CRM or backend systems.

Base URL: https://api.paisan.ai/v1
Latency: <300ms SLA 30+ Indian Dialects

1. Quickstart Guide

Dispatch your first AI phone call in under 2 minutes. Install an official client library or make standard HTTP requests using any language.

Terminal / Package Manager 
# Install via npm
npm install @paisan/voice-sdk

# Or install via python pip
pip install paisan-voice

2. Authentication

Authenticate all API requests by providing your API secret key in the Authorization HTTP header.

Generate your production key in the dashboard

Keys start with psn_live_ for production and psn_test_ for sandboxing.

Manage Keys in Platform →
Authorization Header 
Authorization: Bearer psn_live_YOUR_SECRET_KEY
POST

/v1/calls/dispatch

Initiates an immediate outbound AI phone call to an Indian mobile or landline number with specific language, accent, and personalized context.

Request Body Parameters

Field Type Description
phoneNumber Required string E.164 formatted Indian number (e.g. +919876543210).
agentId Required string The unique identifier of your configured voice agent.
language Optional string Defaults to hi-IN (Hindi/Hinglish). Supports ta-IN, te-IN, kn-IN, mr-IN, etc.
variables Optional object Dynamic lead attributes like customer name, EMI amount, appointment slot, or cart value.
webhookUrl Optional string HTTPS callback endpoint to receive call disposition and transcript when the call finishes. 
curl -X POST https://api.paisan.ai/v1/calls/dispatch \
  -H "Authorization: Bearer psn_live_sec_89df201" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+919876543210",
    "agentId": "ag_emi_recovery_v3",
    "language": "hi-IN",
    "variables": {
      "customerName": "Rahul Sharma",
      "emiAmount": "₹4,250",
      "dueDate": "24th October"
    },
    "webhookUrl": "https://api.yourbusiness.com/webhooks/paisan"
  }'

200 OK Response

{
  "success": true,
  "callId": "call_9823f0a1d48c",
  "status": "queued",
  "phoneNumber": "+919876543210",
  "agentId": "ag_emi_recovery_v3",
  "estimatedLatencyMs": 284,
  "createdAt": "2026-10-19T01:15:00Z"
}
GET

/v1/calls/{call_id}

Retrieves the full real-time transcript, speaker turns, emotion detection telemetry, and stereo recording audio URL.

Request Example 
curl https://api.paisan.ai/v1/calls/call_9823f0a1d48c \
  -H "Authorization: Bearer psn_live_sec_89df201"

Response Body

{
  "callId": "call_9823f0a1d48c",
  "durationSeconds": 78,
  "disposition": "PROMISE_TO_PAY",
  "sentiment": "POSITIVE",
  "recordingUrl": "https://storage.paisan.ai/recordings/call_9823f0a1d48c.mp3",
  "transcripts": [
    {
      "speaker": "agent",
      "text": "Namaste Rahul ji, main Paisan Bank se baat kar rahi hoon. Kya aap sun paa rahe hain?",
      "timestampMs": 340
    },
    {
      "speaker": "customer",
      "text": "Haan ji boliye, main kal dopahar tak pay kar dunga.",
      "timestampMs": 1420
    }
  ],
  "costInCredits": 2
}
POST

/v1/agents/{id}/knowledge

Inject on-the-fly business FAQs, pricing tables, or catalog updates directly into your voice agent's retrieval memory without redeploying.

JSON Payload 
curl -X POST https://api.paisan.ai/v1/agents/ag_sales_01/knowledge \
  -H "Authorization: Bearer psn_live_sec_89df201" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "Diwali Offer 2026",
    "qaPairs": [
      {
        "question": "Kya koi festive discount chal raha hai?",
        "answer": "Haan ji! Is hafte hamara 20% cashback chal raha hai up to 5,000 rupees."
      }
    ]
  }'

3. Webhooks & Event Streams

Receive real-time HTTPS POST notifications for call events like call.completed, call.failed, and human.handoff_requested.

Verifying Webhook Signatures

Each webhook request contains a X-Paisan-Signature header generated with HMAC-SHA256 using your webhook signing secret.

Node.js Signature Verification 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

4. Error Codes & Statuses

Status Error Code Resolution
400 INVALID_PHONE_NUMBER Ensure phone number is in valid E.164 format (+91).
401 UNAUTHORIZED API key missing or invalid. Check your Authorization header.
402 INSUFFICIENT_CREDITS Wallet balance exhausted. Recharge credits in the platform.
429 RATE_LIMIT_EXCEEDED You have exceeded the maximum concurrent outbound channels for your plan tier.