ZeroVoice API Reference

Base URL: https://your-instance.up.railway.app

All endpoints require authentication via Authorization: Bearer <JWT> or X-API-Key: <key> header.

---

Calls

Place outbound call

POST /api/v1/calls/outbound

Field	Type	Required	Description
from_number	string	Yes	E.164 caller ID or Number ID
to_number	string	Yes	E.164 destination number
record	boolean	No	Record the call (default: false)
queue_id	UUID	No	Route through a specific queue
status_callback_url	string	No	Webhook URL for status updates

Get live calls

GET /api/v1/calls/live?queue_id=<uuid>&agent_id=<uuid>

Search call logs

GET /api/v1/calls/logs?from=<number>&to=<number>&direction=<inbound|outbound>&disposition=<value>&date_start=<iso>&date_end=<iso>&page=1&limit=25

Get call by ID

GET /api/v1/calls/{call_id}

Transfer call

POST /api/v1/calls/{call_id}/transfer

Body: {"target_number": "+15551234567", "transfer_type": "warm"}

Hang up call

POST /api/v1/calls/{call_id}/hangup

Get call recordings

GET /api/v1/calls/{call_id}/recordings

Get call notes

GET /api/v1/calls/{call_id}/notes

---

SMS

Send SMS

POST /api/v1/sms/send

Field	Type	Required	Description
from_number	string	Yes	E.164 sender number
to_number	string	Yes	E.164 recipient
body	string	Yes	Message text (max 1600 chars)
media_urls	string[]	No	Media URLs for MMS
status_callback_url	string	No	Webhook URL for delivery status

DNC enforcement: Outbound SMS to numbers on the org's Do-Not-Call list returns HTTP 451.

---

Contacts

Create contact

POST /api/v1/contacts

Field	Type	Required	Description
name	string	Yes	Full name
phone	string	Yes	E.164 phone number
email	string	No	Email address
company	string	No	Company name
tags	string[]	No	Categorization tags

List contacts

GET /api/v1/contacts?search=<term>&page=1&limit=25

Get contact call history

GET /api/v1/contacts/{contact_id}/calls

---

Phone Numbers

List numbers

GET /api/v1/numbers?page=1&limit=25

Search available numbers

POST /api/v1/numbers/search

Field	Type	Required	Description
country	string	Yes	ISO country code (US, CA, GB)
number_type	string	Yes	local, toll_free, or mobile
area_code	string	No	Desired area code
contains	string	No	Pattern to match
limit	integer	No	Max results (1-50, default 20)

Purchase number

POST /api/v1/numbers/purchase

Body: {"phone_number": "+18005551234", "friendly_name": "Support Line"}

Configure number routing

PUT /api/v1/numbers/{number_id}/config

Body: {"friendly_name": "Main", "routing": {"type": "ivr", "target_id": "..."}}

Release number

DELETE /api/v1/numbers/{number_id}

---

Transcripts

Get transcript by call

GET /api/v1/transcripts/call/{call_id}

Search transcripts

GET /api/v1/transcripts/search?q=<query>&page=1&limit=25

List transcripts

GET /api/v1/transcripts?page=1&limit=25

---

Voicemails

List voicemails

GET /api/v1/voicemails?status=<new|read|archived>&page=1&limit=25

Get voicemail

GET /api/v1/voicemails/{voicemail_id}

---

Compliance

Check DNC status

GET /api/v1/compliance/dnc?phone=<e164_number>

List DNC numbers

GET /api/v1/compliance/dnc?page=1&limit=25

GDPR export request

POST /api/v1/compliance/gdpr/export

GDPR delete request

POST /api/v1/compliance/gdpr/delete

---

Analytics

Call volume

GET /api/v1/analytics/call-volume?interval=<hour|day|week|month>&date_start=<iso>&date_end=<iso>

Agent performance

GET /api/v1/analytics/agent-performance?date_start=<iso>&date_end=<iso>

Queue reports

GET /api/v1/analytics/queue-reports

Disposition distribution

GET /api/v1/analytics/dispositions

Sentiment analysis

GET /api/v1/analytics/sentiment/{call_id}

---

Health

Liveness (no auth)

GET /health

Readiness (no auth)

GET /health/ready

Checks: database, Twilio, Stripe, ZeroDB. Returns 200 when all healthy, 503 on failure.

---

Error responses

All errors follow this format:

{
  "error": "Bad Request",
  "code": "bad_request",
  "details": { "field": "to_number", "message": "Invalid E.164 format" }
}

Code	Meaning
400	Invalid request parameters
401	Missing or invalid authentication
403	Insufficient permissions
404	Resource not found
422	Validation error
429	Rate limit exceeded (200 req/min per tenant)
451	Blocked by compliance (DNC list)
503	Service unavailable (Twilio circuit breaker open)