API Documentation

curl https://phonestack.com/api/v1/calls \
  -H "Authorization: Bearer ps_live_YOUR_API_KEY"

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Phone number is required"
  }
}

{
  "success": true,
  "data": [...],
  "meta": {
    "limit": 50,
    "next_cursor": "abc123",
    "has_more": true
  }
}

curl -X POST https://phonestack.com/api/v1/contacts \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Martinez",
    "phone": "+12145551234",
    "email": "john@example.com",
    "company": "ABC Corp",
    "tags": ["website_lead"],
    "campaign_id": "CAMPAIGN_ID",
    "custom_fields": {"source": "contact_form"}
  }'

curl -X POST https://phonestack.com/api/v1/contacts/bulk \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"first_name": "John", "phone": "+12145551234"},
      {"first_name": "Jane", "phone": "+13105559876"}
    ],
    "campaign_id": "CAMPAIGN_ID",
    "tags": ["batch_import"]
  }'

curl "https://phonestack.com/api/v1/contacts?tag=website_lead&limit=20" \
  -H "Authorization: Bearer ps_live_YOUR_KEY"

curl "https://phonestack.com/api/v1/calls?campaign_id=CAMP_ID&disposition=hot_lead&include=transcript" \
  -H "Authorization: Bearer ps_live_YOUR_KEY"

{
  "id": "call_xyz",
  "campaign_id": "camp_abc",
  "contact_id": "ct_123",
  "status": "completed",
  "direction": "outbound",
  "from_number": "+12145550123",
  "to_number": "+12145551234",
  "transferred_to": null,
  "talk_duration_seconds": 154,
  "cost_cents": 63,
  "cost_breakdown": {"twilio": 23, "gemini": 35, "claude": 5},
  "analysis": {
    "disposition": "hot_lead",
    "sentiment": "positive",
    "summary": "Interested in consultation...",
    "meeting_booked": true,
    "ai_confidence_score": 92
  },
  "tool_executions": [
    {"tool": "check_availability", "status": "success"},
    {"tool": "request_meeting", "status": "success"}
  ]
}

# Start a campaign
curl -X POST https://phonestack.com/api/v1/campaigns/CAMP_ID/start \
  -H "Authorization: Bearer ps_live_YOUR_KEY"

# Pause a campaign
curl -X POST https://phonestack.com/api/v1/campaigns/CAMP_ID/pause \
  -H "Authorization: Bearer ps_live_YOUR_KEY"

curl -X POST https://phonestack.com/api/v1/custom-fields \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "budget_range",
    "type": "enum",
    "description": "Prospect budget range for the project",
    "category": "both",
    "required": false,
    "options": ["under_10k", "10k_50k", "50k_100k", "100k_plus"]
  }'

# First, create your custom fields
curl -X POST https://phonestack.com/api/v1/custom-fields \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -d '{"name": "budget_range", "type": "enum", "description": "Budget", "options": ["under_10k", "10k_50k", "50k_plus"]}'

curl -X POST https://phonestack.com/api/v1/custom-fields \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -d '{"name": "decision_timeline", "type": "string", "description": "When they plan to make a decision"}'

# Then bind them to a profile
curl -X PATCH https://phonestack.com/api/v1/profiles/PROFILE_ID \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -d '{"extract_fields": ["budget_range", "decision_timeline"]}'

# Now every call using this profile auto-extracts both fields
curl -X POST https://phonestack.com/api/v1/calls/trigger \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -d '{"profile_id": "PROFILE_ID", "phone": "+14155551234"}'

curl -X POST https://phonestack.com/api/v1/reports/REPORT_ID/execute \
  -H "Authorization: Bearer ps_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_range": "last_7_days"}'

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === expected;
}

// In your webhook handler:
app.post("/webhooks/phonestack", (req, res) => {
  const sig = req.headers["x-phonestack-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), sig, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.status(200).send("OK");
});

{
  "event": "call.completed",
  "timestamp": "2025-04-03T14:34:12Z",
  "organization_id": "org_abc123",
  "data": {
    "call_id": "call_xyz",
    "campaign_id": "camp_def",
    "direction": "outbound",
    "talk_duration_seconds": 154,
    "cost_cents": 63,
    "analysis": {
      "disposition": "hot_lead",
      "summary": "Interested in consultation...",
      "meeting_booked": true
    },
    "transcript": [
      {"speaker": "agent", "text": "Hi John...", "timestamp_seconds": 0}
    ]
  }
}

MCP Server URL: https://mcp.phonestack.com/mcp

MCP Server URL: https://mcp.phonestack.com/mcp

// On your website form submit
async function onFormSubmit(formData) {
  await fetch("https://phonestack.com/api/v1/contacts", {
    method: "POST",
    headers: {
      "Authorization": "Bearer ps_live_YOUR_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      first_name: formData.name,
      phone: formData.phone,
      email: formData.email,
      campaign_id: "YOUR_CAMPAIGN_ID",
      tags: ["website_lead"],
      custom_fields: { source_page: window.location.pathname }
    })
  });
}

import requests

API_KEY = "ps_live_YOUR_KEY"
CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"

def sync_new_leads(crm_leads):
    contacts = [
        {
            "first_name": lead["first_name"],
            "last_name": lead["last_name"],
            "phone": lead["phone"],
            "email": lead["email"],
            "custom_fields": {"crm_id": lead["id"]},
        }
        for lead in crm_leads
    ]

    resp = requests.post(
        "https://phonestack.com/api/v1/contacts/bulk",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"contacts": contacts, "campaign_id": CAMPAIGN_ID}
    )
    print(f"Synced {resp.json()['data']['created']} leads")

// Receive call results and update your CRM
app.post("/webhooks/phonestack", (req, res) => {
  const { event, data } = req.body;

  if (event === "call.completed") {
    updateCRM(data.contact_id, {
      last_call: data.timestamp,
      disposition: data.analysis.disposition,
      summary: data.analysis.summary,
      meeting_booked: data.analysis.meeting_booked,
    });

    if (data.analysis.disposition === "hot_lead") {
      notifySalesTeam(data);
    }
  }

  res.status(200).send("OK");
});