Create a scoped read-only key
An organization administrator opens Settings → API & automation. API access requires an eligible plan, such as Team. Create a key with only the resource scopes your application needs. Copy the secret once and store it outside source control. Keys expire after 30 days and inherit the owner's current permissions; revoke unused keys.
The public REST contract provides GET resources under /api/v1: calls, statistics, employees, teams, dashboards, integrations and organization. Each resource requires its corresponding read scope, such as calls:read. The authenticated identity fixes the organization; a request cannot select another tenant. Phone numbers are masked. Consult the OpenAPI reference for exact filters and responses.
Make a request
Set CALLMETRA_ORIGIN to your actual HTTPS application origin and CALLMETRA_API_KEY to your key in the environment. Do not paste a real key into this example.
curl --fail --silent --show-error \
-H "Authorization: Bearer $CALLMETRA_API_KEY" \
"$CALLMETRA_ORIGIN/api/v1/calls?page=1&pageSize=20"
Receive and send events
Custom incoming call webhooks are configured in Integrations. Their generated bearer token is distinct from a read-only API key. Use schemaVersion 1, a unique event ID, call ID, occurredAt with an explicit time-zone offset, direction and employee extension. A 202 response means durable acceptance, not completed processing. Keep generated ingress URLs and tokens private.
Outbound webhooks send selected lifecycle events to your own public HTTPS URL. Private/local destinations and redirects are blocked. Verify Callmetra-Timestamp and Callmetra-Signature against the exact raw request body. The signature is HMAC-SHA256 of the Unix timestamp, a dot and the body; the signature value uses the v1= prefix. Reject timestamps outside a five-minute window, use constant-time comparison and deduplicate the event ID. Delivery is at least once, with up to eight attempts. Store the signing secret privately and never verify a re-serialized JSON body.
For setup and delivery failures, see troubleshooting.
Pagination and errors
List requests use one-based page numbers and pageSize between 1 and 100. Responses contain data and pagination with page, pageSize, total and totalPages. Calls accept period, team, employee, direction, status and search filters as specified in OpenAPI. Keys are limited to 120 authorized requests per minute. Respect Retry-After on HTTP 429. HTTP 401 means missing or revoked authentication; 403 means insufficient scope, role or plan. The error object includes status, code, message and requestId. Keep the request ID for support, without sharing your key.
Custom ingress example
This fictional payload starts an incoming call. Send subsequent call.answered and call.ended events with the same callId and new event IDs. Use real event timestamps with an explicit offset; do not replay the example into a live integration.
{
"schemaVersion": 1,
"id": "example-start-1",
"event": "call.started",
"callId": "example-call-1",
"occurredAt": "2026-11-21T10:00:00+01:00",
"direction": "inbound",
"employeeExtension": "101",
"number": "+12025550101"
}
Verify an outbound signature
This receiver helper checks the raw UTF-8 body before parsing it. Pass your signing secret from secure server configuration. After verification, durably deduplicate Callmetra-Event-Id before performing side effects.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, timestamp, signature, secret) {
if (!/^\d+$/.test(timestamp || '') ||
Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'v1=' + createHmac('sha256', secret)
.update(timestamp + '.' + rawBody).digest('hex');
const left = Buffer.from(expected);
const right = Buffer.from(signature || '');
return left.length === right.length && timingSafeEqual(left, right);
}