REST API v1

API Documentation

Integrate Voniq voice, SMS, email, and fax spoofing into your stack. Bearer authentication, JSON payloads, predictable rate limits, and prepaid billing per request.

Authentication

Bearer token in Authorization header on every request.

Rate limits

Per-channel limits with burst allowance and Retry-After on 429.

Prepaid billing

Each action debits your balance. Insufficient funds return 402.

Quick start

Base URL: https://api.voniq.cc/v1

Generate an API key in your dashboard. Enterprise unlocks call endpoints; each spoof plan unlocks its channel. Keys are only validated on the Voniq API host — this docs site is static and makes no backend calls.

send-sms.sh
curl -X POST https://api.voniq.cc/v1/sms/send \
  -H "Authorization: Bearer vnq_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "ALERT",
    "to": "+491701234567",
    "message": "Hello from Voniq API"
  }'
TLS 1.2+ requiredJSON or multipartIdempotency-Key on POSTHTTPS only

Rate limits

ChannelLimitPlan required
Voice / SIP REST60 requests / 1 minute (burst 15)Enterprise plan required
SMS Spoof120 requests / 1 minute (burst 30)SMS Spoof plan required
Email Spoof30 requests / 1 minute (burst 10)Email Spoof plan required
Fax Spoof20 requests / 1 minute (burst 5)Fax Spoof plan required
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After on 429.

Pagination

List endpoints return cursor-based pages. Pass ?limit= (max 100) and ?starting_after= from the previous response.

list-calls.http
GET https://api.voniq.cc/v1/calls?limit=25&starting_after=call_8f2a9c

{
  "data": […],
  "has_more": true,
  "next_cursor": "call_7b1c02"
}

Idempotency

Safe retries for POST requests within a 24-hour window.

idempotent-send.http
POST https://api.voniq.cc/v1/sms/send
Authorization: Bearer vnq_live_…
Idempotency-Key: order-9281-sms-1
Content-Type: application/json

{ "from": "ALERT", "to": "+49…", "message": "…" }

Webhooks

Configure HTTPS webhook URLs in the dashboard to receive delivery events. Payloads are signed with HMAC-SHA256 in the Voniq-Signature header.

sms.deliveredsms.failedemail.deliveredemail.openedfax.completedcall.completed
webhook-payload.json
POST https://your-server.com/voniq/webhook
Voniq-Signature: t=1719590400,v1=8f4e2c…

{
  "type": "sms.delivered",
  "data": { "id": "sms_3d91bf", "to": "+49…" }
}

Endpoints by channel

Select a channel to view methods, payloads, and sample responses.

Voice & Calls API

Place outbound calls, fetch CDRs, and manage SIP credentials programmatically. Requires an active Enterprise call plan and prepaid balance.

Header: Authorization: Bearer vnq_live_…

POSThttps://api.voniq.cc/v1/calls/outbound

Initiate an outbound VoIP call

post-request
{
  "to": "+493012345678",
  "from": "+498001234567",
  "caller_id": "Anonymous",
  "max_duration_sec": 3600
}
response.json
{
  "id": "call_8f2a9c",
  "status": "queued",
  "estimated_cost_eur": 0.04
}
GEThttps://api.voniq.cc/v1/calls/{call_id}

Retrieve call status and final cost

response.json
{
  "id": "call_8f2a9c",
  "status": "completed",
  "duration_sec": 142,
  "cost_eur": 0.03
}
GEThttps://api.voniq.cc/v1/calls

List recent calls with pagination

response.json
{
  "data": [{ "id": "call_8f2a9c", "to": "+49…", "cost_eur": 0.03 }],
  "has_more": true
}
GEThttps://api.voniq.cc/v1/balance

Current prepaid account balance

response.json
{ "balance_eur": 12.50, "currency": "EUR" }

Security best practices

Never expose keys in the browser

API keys belong on your server only. The Voniq dashboard key is for backend integrations — do not embed it in client-side JavaScript.

Rotate on compromise

Regenerate keys from the dashboard if a key leaks. Old keys stop working immediately.

Use Idempotency-Key on POST

Pass a unique Idempotency-Key header when retrying sends to avoid duplicate SMS, email, or fax charges.

Respect 429 responses

Backoff exponentially when rate limited. Burst limits protect shared infrastructure for all customers.

The current stable version is v1. Breaking changes ship only in new major paths (/v2). v1 remains available for at least 12 months after a successor launches.

Error codes

400bad_requestInvalid parameters or malformed JSON body
401unauthorizedMissing or invalid API key
403forbiddenAPI key disabled or plan does not include this channel
402payment_requiredInsufficient prepaid balance
429rate_limit_exceededToo many requests — see rate limits and Retry-After header
500internal_errorUnexpected server error — retry with exponential backoff

Ready to integrate

Connect Voniq to your stack in minutes

Upgrade to Enterprise or add a spoof plan, then create your API key in the dashboard. All channels share one key with scoped access per subscription.