--- title: "API Reference" description: "ZeroVoice API reference — endpoints for calls, SMS, voicemail, and recordings" canonical: "https://docs.ainative.studio/docs/zerovoice/api-reference" last-updated: "2026-11-02T18:12:43.468Z" --- # API Reference Source: https://docs.ainative.studio/docs/zerovoice/api-reference > ZeroVoice API reference — endpoints for calls, SMS, voicemail, and recordings # ZeroVoice API Reference Base URL: `https://your-zerovoice-instance.example.com` All endpoints require authentication via `Authorization: Bearer ` or `X-API-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=&agent_id= ``` ### Search call logs ``` GET /api/v1/calls/logs?from=&to=&direction=&disposition=&date_start=&date_end=&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=&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=&page=1&limit=25 ``` ### List transcripts ``` GET /api/v1/transcripts?page=1&limit=25 ``` --- ## Voicemails ### List voicemails ``` GET /api/v1/voicemails?status=&page=1&limit=25 ``` ### Get voicemail ``` GET /api/v1/voicemails/{voicemail_id} ``` --- ## Compliance ### Check DNC status ``` GET /api/v1/compliance/dnc?phone= ``` ### 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=&date_start=&date_end= ``` ### Agent performance ``` GET /api/v1/analytics/agent-performance?date_start=&date_end= ``` ### Queue reports ``` GET /api/v1/analytics/queue-reports ``` ### Disposition distribution ``` GET /api/v1/analytics/dispositions ``` ### Sentiment analysis ``` GET /api/v1/analytics/sentiment/{call_id} ``` --- ## Payments & Billing ### Create checkout session ``` POST /api/v1/payments/checkout ``` Body: `{"plan": "pro", "success_url": "https://...", "cancel_url": "https://..."}` Plans: `pro` ($49/mo), `business` ($149/mo), `enterprise` ($499/mo). Returns a Stripe checkout URL. ### Get subscription ``` GET /api/v1/payments/subscription ``` ### Payment history ``` GET /api/v1/payments/history ``` ### Billing portal ``` POST /api/v1/payments/portal-session ``` Returns a Stripe billing portal URL for self-service subscription management. ### Usage summary ``` GET /api/v1/billing/usage ``` Returns current billing period usage: outbound/inbound minutes, SMS segments, active seats. --- ## 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: ```json { "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) |