PhonePilotv2.5
Developer Documentation & Specs

PhonePilot Enterprise
REST APIs, Webhooks & Protocol

Integrate your CRM, build automated device workflows, and stream screen frames using standard REST endpoints and HMAC-SHA256 verified webhooks.

REST API Reference

Authenticate via Authorization: Bearer <TOKEN> or x-api-key: <KEY> header.

POST/api/companion/relay
v2.5 Endpoints

Mobile companion bi-directional telemetry exchange and command dispatch.

Example JSON Payload:
{
  "action": "dispatch",
  "deviceId": "cmp_device_uuid",
  "command": {
    "action": "TAP",
    "x": 540,
    "y": 1200
  }
}
GET | POST/api/hunter
v2.5 Endpoints

Full CRUD on leads, live directory scraping, lead scoring, and RFC-4180 CSV export.

Example JSON Payload:
{
  "action": "scrape",
  "query": "Healthcare Clinic",
  "location": "Dallas, TX",
  "limit": 10
}
GET | POST/api/campaigns
v2.5 Endpoints

Campaign schedule management and Redis-queued bulk outreach dispatch.

Example JSON Payload:
{
  "action": "dispatch",
  "leadIds": [
    "lead_1",
    "lead_2"
  ],
  "channel": "EMAIL",
  "message": "Following up on enterprise automation partnership."
}
POST | DELETE/api/revops
v2.5 Endpoints

Lifecycle stage progression (LEAD ➔ SQL ➔ CUSTOMER), auto-invoicing & webhook events.

Example JSON Payload:
{
  "action": "transition_stage",
  "leadId": "lead_cuid",
  "targetStage": "CUSTOMER",
  "dealValue": 1200
}
POST | DELETE/api/webhooks
v2.5 Endpoints

Register, update, and manage webhook subscription endpoints with secret HMAC keys.

Example JSON Payload:
{
  "name": "HubSpot Pipeline Sync",
  "targetUrl": "https://api.yourdomain.com/webhooks/phonepilot",
  "subscribedEvents": [
    "lead.scraped",
    "automation.completed"
  ],
  "serviceType": "CUSTOM"
}
POST/api/ai/test-connection
v2.5 Endpoints

Real outbound HTTP test measuring live round-trip latency to LLM providers.

Example JSON Payload:
{
  "provider": "groq",
  "apiKey": "gsk_...",
  "baseUrl": "https://api.groq.com/openai/v1",
  "model": "llama-3.3-70b-versatile"
}
POST/api/browser/run
v2.5 Endpoints

Executes server-side headless browser tasks (DOM click, text input, screenshot).

Example JSON Payload:
{
  "targetUrl": "https://example.com",
  "taskType": "EXTRACT_LEADS",
  "actions": [
    {
      "type": "NAVIGATE",
      "url": "https://example.com"
    },
    {
      "type": "SCREENSHOT"
    }
  ]
}

Webhooks & HMAC-SHA256 Signature Verification

Every webhook event includes an X-PhonePilot-Signature header.

Supported Webhook Event Identifiers
lead.scrapedlead.verifiedautomation.completeddevice.disconnectedinvoice.paidping.test
Node.js / TypeScript Verification Implementation
// Node.js Webhook HMAC-SHA256 Verification
import crypto from "crypto";

export function verifyPhonePilotSignature(
  rawBody: string,
  signatureHeader: string,
  secretKey: string
): boolean {
  // Strip 'sha256=' prefix if present
  const receivedHash = signatureHeader.replace(/^sha256=/, "");
  
  const computedHash = crypto
    .createHmac("sha256", secretKey)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(receivedHash, "hex"),
    Buffer.from(computedHash, "hex")
  );
}
Python 3 Verification Implementation
# Python Webhook HMAC-SHA256 Verification
import hmac
import hashlib

def verify_signature(raw_body: bytes, signature_header: str, secret_key: str) -> bool:
    received_hash = signature_header.replace("sha256=", "")
    computed_hash = hmac.new(
        secret_key.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(received_hash, computed_hash)

Android Companion Protocol Specs

Zero-root accessibility protocol streaming Base64 JPEG frames over WebSocket or HTTP relay.

The native Android Companion application implements PhonePilotAccessibilityService with android:canTakeScreenshot="true". When activated:

  • Captures live screen snapshots via AccessibilityService.takeScreenshot().
  • Compresses bitmap into 60-80% quality JPEG Base64 payload.
  • Transmits frames every 1.5–2s to /api/companion/relay.
  • Receives queued commands: TAP, SWIPE, TYPE, and executes them within 1 second.