Developer guide

# Put the key in the environment once. Every curl example reads it from there.
export VOCATECH_API_KEY="paste-your-key-here"

# That is all curl needs.

// vocatech.mjs: a tiny client. Node 18 or newer, no packages.
const BASE = 'https://api.vocatech.com';
const KEY = process.env.VOCATECH_API_KEY;

export async function vt(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const text = await res.text();
  let data = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    data = { raw: text };
  }
  if (!res.ok) {
    const err = new Error(`${res.status} ${errorText(data)}`);
    err.status = res.status;
    err.retryAfter = Number(res.headers.get('retry-after')) || null;
    err.body = data;
    throw err;
  }
  return data;
}

// The API writes errors in a few shapes. This reads all of them.
export function errorText(body) {
  if (!body) return '';
  if (typeof body.error === 'string') return body.message || body.error;
  if (body.error) return body.error.message || body.error.description || '';
  return body.raw || '';
}

# vocatech.py: a tiny client. Python 3.8 or newer, and: pip install requests
import os

import requests

BASE = "https://api.vocatech.com"
KEY = os.environ["VOCATECH_API_KEY"]


def error_text(body):
    """The API writes errors in a few shapes. This reads all of them."""
    if not isinstance(body, dict):
        return ""
    err = body.get("error")
    if isinstance(err, str):
        return body.get("message") or err
    if isinstance(err, dict):
        return err.get("message") or err.get("description") or ""
    return ""


class VocatechError(Exception):
    def __init__(self, status, body, retry_after):
        super().__init__(f"{status} {error_text(body)}")
        self.status = status
        self.body = body
        self.retry_after = retry_after


def vt(method, path, body=None, params=None):
    r = requests.request(
        method,
        BASE + path,
        params=params,
        json=body,
        headers={"Authorization": f"Bearer {KEY}"},
        timeout=60,
    )
    try:
        data = r.json() if r.content else None
    except ValueError:
        data = {"raw": r.text}
    if not r.ok:
        retry = r.headers.get("Retry-After")
        raise VocatechError(r.status_code, data, int(retry) if retry else None)
    return data

<?php
// vocatech.php: a tiny client. PHP 8.1 or newer, with the curl extension.
const VT_BASE = 'https://api.vocatech.com';

/** The API writes errors in a few shapes. This reads all of them. */
function vt_error_text(?array $body): string
{
    $error = $body['error'] ?? null;
    if (is_string($error)) {
        return (string) ($body['message'] ?? $error);
    }
    if (is_array($error)) {
        return (string) ($error['message'] ?? $error['description'] ?? '');
    }
    return '';
}

final class VocatechError extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly ?array $body,
        public readonly ?int $retryAfter
    ) {
        parent::__construct($status . ' ' . vt_error_text($body), $status);
    }
}

function vt(string $method, string $path, ?array $body = null): ?array
{
    $retryAfter = null;
    $headers = ['Authorization: Bearer ' . getenv('VOCATECH_API_KEY')];
    $ch = curl_init(VT_BASE . $path);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 60,
        CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
            if (stripos($line, 'Retry-After:') === 0) {
                $retryAfter = (int) trim(substr($line, 12));
            }
            return strlen($line);
        },
    ]);
    $raw = curl_exec($ch);
    if ($raw === false) {
        throw new RuntimeException('Network error: ' . curl_error($ch));
    }
    $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $data = $raw === '' ? null : json_decode($raw, true);
    if ($status >= 400) {
        throw new VocatechError($status, is_array($data) ? $data : null, $retryAfter);
    }
    return is_array($data) ? $data : null;
}

curl https://api.vocatech.com/v1/whoami \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

const me = await vt('GET', '/v1/whoami');
console.log(me.company_id, me.client_ip, me.ip_restricted);

from vocatech import vt

me = vt("GET", "/v1/whoami")
print(me["company_id"], me["client_ip"], me["ip_restricted"])

<?php
require __DIR__ . '/vocatech.php';

$me = vt('GET', '/v1/whoami');
echo $me['company_id'], ' ', $me['client_ip'], PHP_EOL;

# No dates: today, in New York time
curl https://api.vocatech.com/v1/calls \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# One day, in your own time zone
curl "https://api.vocatech.com/v1/calls?start_date=2026-09-23&end_date=2026-09-23&timezone=America/Chicago" \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

const today = await vt('GET', '/v1/calls');
console.log(`${today.meta.total_calls} calls today`);

for (const call of today.calls) {
  console.log(call.start_time, call.direction, call.remote_number, call.extension_name);
}

from vocatech import vt

today = vt("GET", "/v1/calls")
print(today["meta"]["total_calls"], "calls today")

for call in today["calls"]:
    print(call["start_time"], call["direction"], call["remote_number"], call["extension_name"])

<?php
require __DIR__ . '/vocatech.php';

$today = vt('GET', '/v1/calls');
echo $today['meta']['total_calls'], " calls today\n";

foreach ($today['calls'] as $call) {
    echo "{$call['start_time']} {$call['direction']} {$call['remote_number']} {$call['extension_name']}\n";
}

# 1. Today's calls, New York time, 500 a page, oldest first
curl "https://api.vocatech.com/v1/calls?sort=day_asc&limit=500&page=1" \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# 2. A recording: ask for a signed link, then download it with no key (uses jq)
url=$(curl -s https://api.vocatech.com/v1/media/rec_58213407 \
  -H "Authorization: Bearer $VOCATECH_API_KEY" | jq -r .url)
curl -o rec_58213407.mp3 "$url"

import { writeFile } from 'node:fs/promises';
import { vt } from './vocatech.mjs';

// Today, New York time. Add start_date, end_date and timezone for other days.
for (let page = 1, pages = 1; page <= pages; page++) {
  const data = await vt('GET', `/v1/calls?sort=day_asc&limit=500&page=${page}`);
  pages = data.meta.total_pages;

  for (const call of data.calls) {
    for (const leg of call.journey) {
      if (leg.summary) console.log(call.call_id, leg.extension_name, leg.summary);

      if (leg.recording_url) {
        // recording_url is an API address: ask it for a signed download link.
        const media = await vt('GET', new URL(leg.recording_url).pathname);
        const audio = await fetch(media.url); // no key needed, good for 30 minutes
        await writeFile(`${media.id}.${media.format}`, Buffer.from(await audio.arrayBuffer()));
      }
    }
  }
}

from urllib.parse import urlparse

import requests
from vocatech import vt

# Today, New York time. Add start_date, end_date and timezone for other days.
page = 1
while True:
    data = vt("GET", "/v1/calls", params={"sort": "day_asc", "limit": 500, "page": page})

    for call in data["calls"]:
        for leg in call["journey"]:
            if leg["summary"]:
                print(call["call_id"], leg["extension_name"], leg["summary"])

            if leg["recording_url"]:
                # recording_url is an API address: ask it for a signed download link.
                media = vt("GET", urlparse(leg["recording_url"]).path)
                audio = requests.get(media["url"], timeout=120)  # no key needed
                with open(f'{media["id"]}.{media["format"]}', "wb") as f:
                    f.write(audio.content)

    if page >= data["meta"]["total_pages"]:
        break
    page += 1

<?php
require __DIR__ . '/vocatech.php';

// Today, New York time. Add start_date, end_date and timezone for other days.
for ($page = 1, $pages = 1; $page <= $pages; $page++) {
    $data = vt('GET', '/v1/calls?' . http_build_query(['sort' => 'day_asc', 'limit' => 500, 'page' => $page]));
    $pages = $data['meta']['total_pages'];

    foreach ($data['calls'] as $call) {
        foreach ($call['journey'] as $leg) {
            if ($leg['summary']) {
                echo $call['call_id'], ' ', $leg['extension_name'], ': ', $leg['summary'], PHP_EOL;
            }
            if ($leg['recording_url']) {
                // recording_url is an API address: ask it for a signed download link.
                $media = vt('GET', parse_url($leg['recording_url'], PHP_URL_PATH));
                // The signed link needs no key and works for 30 minutes.
                file_put_contents("{$media['id']}.{$media['format']}", file_get_contents($media['url']));
            }
        }
    }
}

# 1. Dry run: checks everything, sends nothing
curl -X POST https://api.vocatech.com/v1/messages \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "text",
    "from": "7185550100",
    "to": "7185550142",
    "message": "Hi Jordan, your appointment is confirmed for Friday at 9 AM.",
    "test": true
  }'

# 2. Send it: the same body without "test"
curl -X POST https://api.vocatech.com/v1/messages \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "text",
    "from": "7185550100",
    "to": "7185550142",
    "message": "Hi Jordan, your appointment is confirmed for Friday at 9 AM."
  }'

import { vt } from './vocatech.mjs';

const text = {
  platform: 'text',
  from: '7185550100', // a texting number on your account
  to: '7185550142',
  message: 'Hi Jordan, your appointment is confirmed for Friday at 9 AM.',
};

// 1. Dry run: checks everything, sends nothing
const check = await vt('POST', '/v1/messages', { ...text, test: true });
console.log('valid:', check.message.valid, 'parts:', check.message.messages_counted);

// 2. Send it
try {
  const res = await vt('POST', '/v1/messages', text);
  if (res.status === 'queued') {
    console.log('queued at position', res.message.position); // 202, API Messaging keys
  } else if (res.message.message_sent) {
    console.log('sent:', res.status); // 201, or 200 into an existing Webex space
  } else {
    console.warn('taken but not sent:', res.message);
  }
} catch (err) {
  if (err.status === 503) console.warn('Not sent. Safe to retry.');
  else if (err.status === 504) console.warn('May have gone out. Check GET /v1/messages first.');
  else throw err;
}

from vocatech import VocatechError, vt

text = {
    "platform": "text",
    "from": "7185550100",  # a texting number on your account
    "to": "7185550142",
    "message": "Hi Jordan, your appointment is confirmed for Friday at 9 AM.",
}

# 1. Dry run: checks everything, sends nothing
check = vt("POST", "/v1/messages", {**text, "test": True})
print("valid:", check["message"]["valid"], "parts:", check["message"]["messages_counted"])

# 2. Send it
try:
    res = vt("POST", "/v1/messages", text)
    if res["status"] == "queued":
        print("queued at position", res["message"]["position"])  # 202, API Messaging keys
    elif res["message"].get("message_sent"):
        print("sent:", res["status"])  # 201, or 200 into an existing Webex space
    else:
        print("taken but not sent:", res["message"])
except VocatechError as err:
    if err.status == 503:
        print("Not sent. Safe to retry.")
    elif err.status == 504:
        print("May have gone out. Check GET /v1/messages first.")
    else:
        raise

<?php
require __DIR__ . '/vocatech.php';

$text = [
    'platform' => 'text',
    'from'     => '7185550100', // a texting number on your account
    'to'       => '7185550142',
    'message'  => 'Hi Jordan, your appointment is confirmed for Friday at 9 AM.',
];

// 1. Dry run: checks everything, sends nothing
$check = vt('POST', '/v1/messages', $text + ['test' => true]);
echo 'parts: ', $check['message']['messages_counted'], PHP_EOL;

// 2. Send it
try {
    $res = vt('POST', '/v1/messages', $text);
    if ($res['status'] === 'queued') {
        echo 'queued at position ', $res['message']['position'], PHP_EOL; // 202
    } elseif (!empty($res['message']['message_sent'])) {
        echo 'sent: ', $res['status'], PHP_EOL; // 201, or 200 into an existing Webex space
    } else {
        echo "taken but not sent\n";
    }
} catch (VocatechError $e) {
    if ($e->status === 503) {
        echo "Not sent. Safe to retry.\n";
    } elseif ($e->status === 504) {
        echo "May have gone out. Check GET /v1/messages first.\n";
    } else {
        throw $e;
    }
}

curl -X POST https://api.vocatech.com/v1/messages \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "text",
    "from": "7185550100",
    "to": "7185550142",
    "message": "Here is the map to our new office.",
    "media": ["https://YOUR_DOMAIN/files/office-map.png"]
  }'

import { vt } from './vocatech.mjs';

const res = await vt('POST', '/v1/messages', {
  platform: 'text',
  from: '7185550100',
  to: '7185550142',
  message: 'Here is the map to our new office.',
  media: ['https://YOUR_DOMAIN/files/office-map.png'], // up to 10 links
});
console.log(res.message.mms, res.message.attachments_sent);

from vocatech import vt

res = vt("POST", "/v1/messages", {
    "platform": "text",
    "from": "7185550100",
    "to": "7185550142",
    "message": "Here is the map to our new office.",
    "media": ["https://YOUR_DOMAIN/files/office-map.png"],  # up to 10 links
})
print(res["message"]["mms"], res["message"]["attachments_sent"])

<?php
require __DIR__ . '/vocatech.php';

$res = vt('POST', '/v1/messages', [
    'platform' => 'text',
    'from'     => '7185550100',
    'to'       => '7185550142',
    'message'  => 'Here is the map to our new office.',
    'media'    => ['https://YOUR_DOMAIN/files/office-map.png'], // up to 10 links
]);
echo $res['message']['attachments_sent'], " attachment(s) sent\n";

curl -X POST https://api.vocatech.com/v1/webhooks \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "url": "https://YOUR_DOMAIN/webhooks/vocatech",
    "event_filters": ["call.ended", "call.transcription", "message.received"]
  }'

import { vt } from './vocatech.mjs';

const hook = await vt('POST', '/v1/webhooks', {
  name: 'CRM sync',
  url: 'https://YOUR_DOMAIN/webhooks/vocatech',
  event_filters: ['call.ended', 'call.transcription', 'message.received'],
});

// hook.secret_key is shown this once. Put it in your secret store now.
console.log('webhook', hook.id, 'created');

from vocatech import vt

hook = vt("POST", "/v1/webhooks", {
    "name": "CRM sync",
    "url": "https://YOUR_DOMAIN/webhooks/vocatech",
    "event_filters": ["call.ended", "call.transcription", "message.received"],
})

# hook["secret_key"] is shown this once. Put it in your secret store now.
print("webhook", hook["id"], "created")

<?php
require __DIR__ . '/vocatech.php';

$hook = vt('POST', '/v1/webhooks', [
    'name'          => 'CRM sync',
    'url'           => 'https://YOUR_DOMAIN/webhooks/vocatech',
    'event_filters' => ['call.ended', 'call.transcription', 'message.received'],
]);

// $hook['secret_key'] is shown this once. Put it in your secret store now.
echo 'webhook ', $hook['id'], " created\n";

curl -X POST https://api.vocatech.com/v1/webhooks/42/test \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

const result = await vt('POST', '/v1/webhooks/42/test');
console.log(result.success, result.status_code, result.error);

from vocatech import vt

result = vt("POST", "/v1/webhooks/42/test")
print(result["success"], result["status_code"], result["error"])

<?php
require __DIR__ . '/vocatech.php';

$result = vt('POST', '/v1/webhooks/42/test');
echo $result['success'] ? 'delivered' : 'failed: ' . $result['error'], PHP_EOL;

# Everything about one number: the last 30 days, up to 5 calls
curl "https://api.vocatech.com/v1/callers/7185550142?days=30&limit=5" \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# Only the contact records
curl "https://api.vocatech.com/v1/contacts/lookup?phone=7185550142" \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

// Everything about one number: the last 30 days, up to 5 calls
const who = await vt('GET', '/v1/callers/7185550142?days=30&limit=5');
const lastCall = who.last_call ? who.last_call.summary : 'no calls';
console.log(who.counts, lastCall);

// Only the contact records, for a screen pop or a CRM match
const hit = await vt('GET', '/v1/contacts/lookup?phone=7185550142');
if (hit.found) console.log(hit.contacts.map((c) => c.fields));

from vocatech import vt

# Everything about one number: the last 30 days, up to 5 calls
who = vt("GET", "/v1/callers/7185550142", params={"days": 30, "limit": 5})
print(who["counts"], who["last_call"]["summary"] if who["last_call"] else "no calls")

# Only the contact records, for a screen pop or a CRM match
hit = vt("GET", "/v1/contacts/lookup", params={"phone": "7185550142"})
if hit["found"]:
    print([c["fields"] for c in hit["contacts"]])

<?php
require __DIR__ . '/vocatech.php';

// Everything about one number: the last 30 days, up to 5 calls
$who = vt('GET', '/v1/callers/7185550142?days=30&limit=5');
echo $who['last_call']['summary'] ?? 'no calls', PHP_EOL;

// Only the contact records, for a screen pop or a CRM match
$hit = vt('GET', '/v1/contacts/lookup?phone=7185550142');
if ($hit['found']) {
    print_r(array_column($hit['contacts'], 'fields'));
}

# 1. Find an agent that may place calls
curl https://api.vocatech.com/v1/agents \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# 2. Have it call one person
curl -X POST https://api.vocatech.com/v1/agents/7/calls \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "7185550142",
    "purpose": "confirm the Friday 9 AM visit",
    "person_name": "Jordan Reyes",
    "reference": "visit-20260925-0900"
  }'

import { vt } from './vocatech.mjs';

// 1. An agent that is on and may place calls
const { agents } = await vt('GET', '/v1/agents');
const agent = agents.find((a) => a.active && a.outgoing_calls);

// 2. One call, to one person
const { call } = await vt('POST', `/v1/agents/${agent.id}/calls`, {
  to: '7185550142',
  purpose: 'confirm the Friday 9 AM visit',
  person_name: 'Jordan Reyes',
  reference: 'visit-20260925-0900',
});
console.log(call.call_sid, call.state); // 202: placed

from vocatech import vt

# 1. An agent that is on and may place calls
agents = vt("GET", "/v1/agents")["agents"]
agent = next(a for a in agents if a["active"] and a["outgoing_calls"])

# 2. One call, to one person
call = vt("POST", f"/v1/agents/{agent['id']}/calls", {
    "to": "7185550142",
    "purpose": "confirm the Friday 9 AM visit",
    "person_name": "Jordan Reyes",
    "reference": "visit-20260925-0900",
})["call"]
print(call["call_sid"], call["state"])  # 202: placed

<?php
require __DIR__ . '/vocatech.php';

// 1. An agent that is on and may place calls
$agents = vt('GET', '/v1/agents')['agents'];
$agent = current(array_filter($agents, fn ($a) => $a['active'] && $a['outgoing_calls']));

// 2. One call, to one person
$call = vt('POST', "/v1/agents/{$agent['id']}/calls", [
    'to'          => '7185550142',
    'purpose'     => 'confirm the Friday 9 AM visit',
    'person_name' => 'Jordan Reyes',
    'reference'   => 'visit-20260925-0900',
])['call'];
echo $call['call_sid'], ' ', $call['state'], PHP_EOL; // 202: placed

curl -X POST https://api.vocatech.com/v1/support/tickets \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Fax line not receiving",
    "message": "Our fax line has not received anything since 8 AM. Please call back.",
    "contact_name": "Maya Chen",
    "contact_phone": "7185550100",
    "reply_by": "call",
    "reference": "helpdesk-4821",
    "source": "Office help desk"
  }'

import { vt } from './vocatech.mjs';

const { ticket } = await vt('POST', '/v1/support/tickets', {
  subject: 'Fax line not receiving',
  message: 'Our fax line has not received anything since 8 AM. Please call back.',
  contact_name: 'Maya Chen',
  contact_phone: '7185550100',
  reply_by: 'call',
  reference: 'helpdesk-4821', // the same reference within 7 days adds to this ticket
  source: 'Office help desk',
});
console.log(ticket.key, ticket.appended ? 'added to the open ticket' : 'opened');

from vocatech import vt

ticket = vt("POST", "/v1/support/tickets", {
    "subject": "Fax line not receiving",
    "message": "Our fax line has not received anything since 8 AM. Please call back.",
    "contact_name": "Maya Chen",
    "contact_phone": "7185550100",
    "reply_by": "call",
    "reference": "helpdesk-4821",  # the same reference within 7 days adds to this ticket
    "source": "Office help desk",
})["ticket"]
print(ticket["key"], "added" if ticket["appended"] else "opened")

<?php
require __DIR__ . '/vocatech.php';

$ticket = vt('POST', '/v1/support/tickets', [
    'subject'       => 'Fax line not receiving',
    'message'       => 'Our fax line has not received anything since 8 AM. Please call back.',
    'contact_name'  => 'Maya Chen',
    'contact_phone' => '7185550100',
    'reply_by'      => 'call',
    'reference'     => 'helpdesk-4821', // the same reference within 7 days adds to this ticket
    'source'        => 'Office help desk',
])['ticket'];
echo $ticket['key'], $ticket['appended'] ? ' added' : ' opened', PHP_EOL;

# 1. Your field names
curl https://api.vocatech.com/v1/contacts/fields \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# 2. Create or update, up to 500 per request
curl -X POST https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "fields": { "Name": "Jordan Reyes", "Phone": "7185550142", "Account": "A-1042" } },
      { "fields": { "Name": "Riley Morgan", "Phone": "7185550143;7185550144", "Account": "A-1043" } }
    ]
  }'

# 3. Delete, up to 500 ids per request
curl -X DELETE https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [5031, 5032] }'

import { vt } from './vocatech.mjs';

// 1. Your field names, and which ones decide "same contact"
const { fields } = await vt('GET', '/v1/contacts/fields');
console.log(fields.map((f) => (f.is_match ? `${f.name} (match)` : f.name)));

// 2. Create or update, up to 500 per request. Use your own field names.
const rows = [
  { fields: { Name: 'Jordan Reyes', Phone: '7185550142', Account: 'A-1042' } },
  { fields: { Name: 'Riley Morgan', Phone: '7185550143;7185550144', Account: 'A-1043' } },
];
for (let i = 0; i < rows.length; i += 500) {
  const res = await vt('POST', '/v1/contacts', { contacts: rows.slice(i, i + 500) });
  console.log(res.summary);
  for (const e of res.errors) console.warn('row', i + e.index, e.message);
}

// 3. Remove the ones you deleted on your side
await vt('DELETE', '/v1/contacts', { ids: [5031, 5032] });

from vocatech import vt

# 1. Your field names, and which ones decide "same contact"
fields = vt("GET", "/v1/contacts/fields")["fields"]
print([f["name"] + (" (match)" if f["is_match"] else "") for f in fields])

# 2. Create or update, up to 500 per request. Use your own field names.
rows = [
    {"fields": {"Name": "Jordan Reyes", "Phone": "7185550142", "Account": "A-1042"}},
    {"fields": {"Name": "Riley Morgan", "Phone": "7185550143;7185550144", "Account": "A-1043"}},
]
for i in range(0, len(rows), 500):
    res = vt("POST", "/v1/contacts", {"contacts": rows[i:i + 500]})
    print(res["summary"])
    for e in res["errors"]:
        print("row", i + e["index"], e["message"])

# 3. Remove the ones you deleted on your side
vt("DELETE", "/v1/contacts", {"ids": [5031, 5032]})

<?php
require __DIR__ . '/vocatech.php';

// 1. Your field names, and which ones decide "same contact"
$fields = vt('GET', '/v1/contacts/fields')['fields'];
foreach ($fields as $f) {
    echo $f['name'], $f['is_match'] ? ' (match)' : '', PHP_EOL;
}

// 2. Create or update, up to 500 per request. Use your own field names.
$rows = [
    ['fields' => ['Name' => 'Jordan Reyes', 'Phone' => '7185550142', 'Account' => 'A-1042']],
    ['fields' => ['Name' => 'Riley Morgan', 'Phone' => '7185550143;7185550144', 'Account' => 'A-1043']],
];
foreach (array_chunk($rows, 500) as $n => $batch) {
    $res = vt('POST', '/v1/contacts', ['contacts' => $batch]);
    foreach ($res['errors'] as $e) {
        echo 'row ', $n * 500 + $e['index'], ': ', $e['message'], PHP_EOL;
    }
}

// 3. Remove the ones you deleted on your side
vt('DELETE', '/v1/contacts', ['ids' => [5031, 5032]]);

# What this key has waiting, and what is left of today
curl https://api.vocatech.com/v1/messages/queue \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# Cancel one waiting message
curl -X DELETE https://api.vocatech.com/v1/messages/queue/48213 \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# Cancel everything still waiting: the wrong batch went in
curl -X DELETE https://api.vocatech.com/v1/messages/queue \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

const { queue, limits } = await vt('GET', '/v1/messages/queue');
console.log(queue.pending, 'waiting,', limits.remaining_today, 'left today');

await vt('DELETE', '/v1/messages/queue/48213'); // one message
const all = await vt('DELETE', '/v1/messages/queue'); // everything still waiting
console.log(all.canceled, 'canceled');

from vocatech import vt

q = vt("GET", "/v1/messages/queue")
print(q["queue"]["pending"], "waiting,", q["limits"]["remaining_today"], "left today")

vt("DELETE", "/v1/messages/queue/48213")  # one message
done = vt("DELETE", "/v1/messages/queue")  # everything still waiting
print(done["canceled"], "canceled")

<?php
require __DIR__ . '/vocatech.php';

$q = vt('GET', '/v1/messages/queue');
echo $q['queue']['pending'], ' waiting, ', $q['limits']['remaining_today'], " left today\n";

vt('DELETE', '/v1/messages/queue/48213'); // one message
$done = vt('DELETE', '/v1/messages/queue'); // everything still waiting
echo $done['canceled'], " canceled\n";

# Remove "test": true to send it for real.
# base64 -w0 is GNU coreutils; on a Mac use: base64 -i intake-form.pdf
curl -X POST https://api.vocatech.com/v1/faxes \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "from": "7185550101",
  "to": "7185550143",
  "filename": "intake-form.pdf",
  "subject": "Signed intake form",
  "test": true,
  "file": "$(base64 -w0 intake-form.pdf)"
}
EOF

import { readFile } from 'node:fs/promises';
import { vt } from './vocatech.mjs';

const res = await vt('POST', '/v1/faxes', {
  from: '7185550101', // one of your fax lines
  to: '7185550143',
  file: (await readFile('intake-form.pdf')).toString('base64'),
  filename: 'intake-form.pdf',
  subject: 'Signed intake form',
  test: true, // remove to send it for real
});
console.log(res.status, res.fax);

import base64

from vocatech import vt

with open("intake-form.pdf", "rb") as f:
    document = base64.b64encode(f.read()).decode()

res = vt("POST", "/v1/faxes", {
    "from": "7185550101",  # one of your fax lines
    "to": "7185550143",
    "file": document,
    "filename": "intake-form.pdf",
    "subject": "Signed intake form",
    "test": True,  # remove to send it for real
})
print(res["status"], res["fax"])

<?php
require __DIR__ . '/vocatech.php';

$res = vt('POST', '/v1/faxes', [
    'from'     => '7185550101', // one of your fax lines
    'to'       => '7185550143',
    'file'     => base64_encode(file_get_contents('intake-form.pdf')),
    'filename' => 'intake-form.pdf',
    'subject'  => 'Signed intake form',
    'test'     => true, // remove to send it for real
]);
echo $res['status'], PHP_EOL;

curl -G https://api.vocatech.com/v1/knowledge/answer \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  --data-urlencode "q=Is there a contract?"

import { vt } from './vocatech.mjs';

const q = new URLSearchParams({ q: 'Is there a contract?' });
const a = await vt('GET', `/v1/knowledge/answer?${q}`);
console.log(a.found ? a.answer : a.note);

from vocatech import vt

a = vt("GET", "/v1/knowledge/answer", params={"q": "Is there a contract?"})
print(a["answer"] if a["found"] else a["note"])

<?php
require __DIR__ . '/vocatech.php';

$a = vt('GET', '/v1/knowledge/answer?' . http_build_query(['q' => 'Is there a contract?']));
echo $a['found'] ? $a['answer'] : $a['note'], PHP_EOL;

# Change what an endpoint receives
curl -X PATCH https://api.vocatech.com/v1/webhooks/42 \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_filters": ["call.ended", "call.transcription"] }'

# Pause it: new events stop
curl -X PATCH https://api.vocatech.com/v1/webhooks/42 \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# Deliveries that failed, newest first
curl "https://api.vocatech.com/v1/webhooks/failures?limit=20" \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# Delete it: its pending retries stop too
curl -X DELETE https://api.vocatech.com/v1/webhooks/42 \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

import { vt } from './vocatech.mjs';

// Change what an endpoint receives
await vt('PATCH', '/v1/webhooks/42', { event_filters: ['call.ended', 'call.transcription'] });

// Pause it: new events stop
await vt('PATCH', '/v1/webhooks/42', { enabled: false });

// Deliveries that failed, newest first
const { failures, meta } = await vt('GET', '/v1/webhooks/failures?limit=20');
console.log(meta.total, failures.map((f) => [f.event_type, f.attempts, f.error_message]));

// Delete it: its pending retries stop too
await vt('DELETE', '/v1/webhooks/42');

from vocatech import vt

# Change what an endpoint receives
vt("PATCH", "/v1/webhooks/42", {"event_filters": ["call.ended", "call.transcription"]})

# Pause it: new events stop
vt("PATCH", "/v1/webhooks/42", {"enabled": False})

# Deliveries that failed, newest first
failed = vt("GET", "/v1/webhooks/failures", params={"limit": 20})
for f in failed["failures"]:
    print(f["event_type"], f["attempts"], f["error_message"])

# Delete it: its pending retries stop too
vt("DELETE", "/v1/webhooks/42")

<?php
require __DIR__ . '/vocatech.php';

// Change what an endpoint receives
vt('PATCH', '/v1/webhooks/42', ['event_filters' => ['call.ended', 'call.transcription']]);

// Pause it: new events stop
vt('PATCH', '/v1/webhooks/42', ['enabled' => false]);

// Deliveries that failed, newest first
$failed = vt('GET', '/v1/webhooks/failures?limit=20');
foreach ($failed['failures'] as $f) {
    echo $f['event_type'], ' ', $f['attempts'], ' ', $f['error_message'], PHP_EOL;
}

// Delete it: its pending retries stop too
vt('DELETE', '/v1/webhooks/42');

// verify.mjs
import crypto from 'node:crypto';

// header:  the X-Vocatech-Signature value
// rawBody: the request body as a Buffer, exactly as it arrived
// secret:  the webhook's secret_key, as the text you were given
export function verifyVocatech(header, rawBody, secret, toleranceSec = 300) {
  const parts = {};
  for (const piece of String(header || '').split(',')) {
    const at = piece.indexOf('=');
    if (at > 0) parts[piece.slice(0, at).trim()] = piece.slice(at + 1).trim();
  }
  if (!/^\d+$/.test(parts.t || '') || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`t=${parts.t}.`)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(parts.v1, 'utf8');
  // timingSafeEqual throws when the lengths differ, so check them first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

# verify.py
import hashlib
import hmac
import time


def verify_vocatech(header, raw_body, secret, tolerance=300):
    """header: X-Vocatech-Signature. raw_body: bytes as received. secret: str."""
    parts = {}
    for piece in (header or "").split(","):
        key, sep, value = piece.strip().partition("=")
        if sep:
            parts[key] = value
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1:
        return False
    if abs(time.time() - int(t)) > tolerance:
        return False

    signed = b"t=" + t.encode() + b"." + raw_body  # bytes, never a decoded str
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())

<?php
// verify.php
// $header: X-Vocatech-Signature. $raw: the body as received. $secret: secret_key.
function vt_verify(string $header, string $raw, string $secret, int $tolerance = 300): bool
{
    $parts = [];
    foreach (explode(',', $header) as $piece) {
        [$key, $value] = array_pad(explode('=', trim($piece), 2), 2, '');
        $parts[$key] = $value;
    }
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', "t={$t}.{$raw}", $secret);
    return hash_equals($expected, $v1); // constant time
}

// Express: npm install express
import express from 'express';
import { verifyVocatech } from './verify.mjs';

const app = express();
const SECRET = process.env.VOCATECH_WEBHOOK_SECRET;
const seen = new Set(); // use your database in production

// express.raw keeps the exact bytes. express.json() would parse them,
// and a re-encoded body no longer matches the signature.
app.post('/webhooks/vocatech', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Vocatech-Signature');
  if (!Buffer.isBuffer(req.body) || !verifyVocatech(signature, req.body, SECRET)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // answer within 5 seconds, then work

  const event = JSON.parse(req.body.toString('utf8'));
  if (seen.has(event.id)) return; // a retry of one you already have
  seen.add(event.id);
  setImmediate(() => handle(event));
});

function handle(event) {
  console.log(event.event_type, event.data);
}

app.listen(3000);

# Flask: pip install flask
import json
import os
import threading

from flask import Flask, abort, request
from verify import verify_vocatech

app = Flask(__name__)
SECRET = os.environ["VOCATECH_WEBHOOK_SECRET"]
seen = set()  # use your database in production


@app.post("/webhooks/vocatech")
def vocatech_webhook():
    raw = request.get_data()  # the exact bytes, before any parsing
    if not verify_vocatech(request.headers.get("X-Vocatech-Signature"), raw, SECRET):
        abort(401)

    event = json.loads(raw)
    if event["id"] not in seen:  # skip a retry of one you already have
        seen.add(event["id"])
        threading.Thread(target=handle, args=(event,)).start()
    return "", 200  # answer within 5 seconds, then work


def handle(event):
    print(event["event_type"], event["data"])

<?php
// Laravel, routes/api.php (API routes skip the CSRF check)
use App\Jobs\HandleVocatechEvent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/vocatech', function (Request $request) {
    $raw = $request->getContent(); // the exact bytes, not $request->all()
    $ok = vt_verify(
        $request->header('X-Vocatech-Signature', ''),
        $raw,
        config('services.vocatech.webhook_secret')
    );
    if (!$ok) {
        abort(401);
    }

    $event = json_decode($raw, true);
    // Cache::add is false when the id is already there: a retry you already have.
    if (Cache::add('vocatech-event:' . $event['id'], true, now()->addDays(8))) {
        HandleVocatechEvent::dispatch($event); // your queued job does the work
    }
    return response()->noContent(); // 204, well within 5 seconds
});

# curl retries 408, 429, 500, 502, 503 and 504 by itself and honors
# Retry-After (curl 7.66 or newer). Use it on reads, never on text sends.
curl --retry 5 --retry-max-time 120 \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  https://api.vocatech.com/v1/calls

import { vt } from './vocatech.mjs';

const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));

export async function withRetry(call, tries = 5) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await call();
    } catch (err) {
      const retryable = err.status === 429 || err.status === 503;
      if (!retryable || attempt >= tries) throw err;
      const wait = err.retryAfter ?? Math.min(60, 2 ** attempt) + Math.random();
      if (wait > 120) throw err; // a day window: stop, do not sleep for hours
      await sleep(wait);
    }
  }
}

const calls = await withRetry(() => vt('GET', '/v1/calls'));

import random
import time

from vocatech import VocatechError, vt


def with_retry(call, tries=5):
    for attempt in range(1, tries + 1):
        try:
            return call()
        except VocatechError as err:
            if err.status not in (429, 503) or attempt == tries:
                raise
            wait = err.retry_after or min(60, 2 ** attempt) + random.random()
            if wait > 120:  # a day window: stop, do not sleep for hours
                raise
            time.sleep(wait)


calls = with_retry(lambda: vt("GET", "/v1/calls"))

<?php
require __DIR__ . '/vocatech.php';

function vt_with_retry(callable $call, int $tries = 5): mixed
{
    for ($attempt = 1; ; $attempt++) {
        try {
            return $call();
        } catch (VocatechError $e) {
            if (!in_array($e->status, [429, 503], true) || $attempt >= $tries) {
                throw $e;
            }
            $wait = $e->retryAfter ?? min(60, 2 ** $attempt) + mt_rand(0, 1000) / 1000;
            if ($wait > 120) {
                throw $e; // a day window: stop, do not sleep for hours
            }
            usleep((int) ($wait * 1000000));
        }
    }
}

$calls = vt_with_retry(fn () => vt('GET', '/v1/calls'));

# Every page, oldest first, until page reaches meta.total_pages (uses jq)
page=1
while :; do
  body=$(curl -s -H "Authorization: Bearer $VOCATECH_API_KEY" \
    "https://api.vocatech.com/v1/messages?start_date=2026-09-01&end_date=2026-09-23&sort=day_asc&limit=500&page=$page")
  echo "$body" | jq -c '.messages[]'
  [ "$page" -ge "$(echo "$body" | jq '.meta.total_pages')" ] && break
  page=$((page + 1))
done

import { vt } from './vocatech.mjs';

// Walks every page of /v1/calls, /v1/messages or /v1/faxes, oldest first.
async function* walk(path, listKey, query = {}) {
  for (let page = 1; ; page++) {
    const qs = new URLSearchParams({ sort: 'day_asc', limit: '500', ...query, page: String(page) });
    const data = await vt('GET', `${path}?${qs}`);
    yield* data[listKey];
    if (page >= data.meta.total_pages) return;
  }
}

for await (const msg of walk('/v1/messages', 'messages', { start_date: '2026-09-01', end_date: '2026-09-23' })) {
  console.log(msg.sent_time, msg.direction, msg.remote_number);
}

from vocatech import vt


def walk(path, list_key, **query):
    """Every page of /v1/calls, /v1/messages or /v1/faxes, oldest first."""
    page = 1
    while True:
        data = vt("GET", path, params={"sort": "day_asc", "limit": 500, **query, "page": page})
        yield from data[list_key]
        if page >= data["meta"]["total_pages"]:
            return
        page += 1


for msg in walk("/v1/messages", "messages", start_date="2026-09-01", end_date="2026-09-23"):
    print(msg["sent_time"], msg["direction"], msg["remote_number"])

<?php
require __DIR__ . '/vocatech.php';

// Every page of /v1/calls, /v1/messages or /v1/faxes, oldest first.
function vt_walk(string $path, string $listKey, array $query = []): Generator
{
    for ($page = 1; ; $page++) {
        $qs = http_build_query(array_merge(['sort' => 'day_asc', 'limit' => 500], $query, ['page' => $page]));
        $data = vt('GET', $path . '?' . $qs);
        yield from $data[$listKey];
        if ($page >= $data['meta']['total_pages']) {
            return;
        }
    }
}

foreach (vt_walk('/v1/messages', 'messages', ['start_date' => '2026-09-01', 'end_date' => '2026-09-23']) as $msg) {
    echo $msg['sent_time'], ' ', $msg['direction'], ' ', $msg['remote_number'], PHP_EOL;
}