Enterprise Call Auditing API: Endpoints and Examples

Practical reference for the v1 call auditing API — the integration channel between the call auditing module and your PBX or telephony platform. Requires an organization with an enterprise plan and an organization API key.

Authentication

Create the key at /dashboard/organization/auditorias (OWNER/ADMIN; up to 10 active keys per organization) and send it with every request:

Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG

• The secret is shown only once at creation — we store only the hash.
• Each key carries scopes (audits:write, audits:read, usage:read, analytics:read, among others); anything not granted is denied by default.
• Rate limit: 60 requests/minute per key.

Creating an audit

curl -X POST https://www.vozparatexto.com.br/api/v1/audits \
  -H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://pbx.suaempresa.com/gravacoes/8841.mp3",
    "webhook_url": "https://api.suaempresa.com/hooks/auditorias",
    "idempotency_key": "chamada-8841",
    "agent_external_id": "maria.souza",
    "team": "vendas-sp"
  }'

Rules:

• Accepts audio_url (only https, public) or upload_id (see below).
• webhook_url is required — the result arrives via webhook, not by polling.
• idempotency_key is durably persisted: resending with the same key does not create a duplicate audit.
• Immediate response: 202 { "audit_id": "...", "status": "queued" }.

Queries: GET /api/v1/audits (list) and GET /api/v1/audits/{id} (details).

Recordings without a public URL

For PBX systems that don't expose a URL, request a temporary upload URL:

curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
  -H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"

The response includes a put_url valid for 1 hour: upload the file with a PUT and use the returned upload_id when creating the audit.

Operations setup and metrics

Webhooks and guarantees

• Deliveries signed with HMAC-SHA256 (X-VPT-Signature + X-VPT-Event); validate before processing.
• 15 s timeout per attempt, up to 6 attempts with backoff from 5 min to 24 h.
• Stuck jobs don't disappear: a queue stopped for >10 min is re-enqueued; processing stuck for >60 min becomes a failure with an error webhook. Every submitted audio generates a final callback.

More details in Webhooks and notifications.

FAQ

Related articles

• Call auditing
• Webhooks and notifications
• Transcription API

Still stuck? Open a ticket — our team responds quickly.