Quickstart

# 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";
}