API Documentation

Build voice campaigns into your applications with the Voxlancer REST API.

Base URL: https://voxlancer-api.proxy.litevps.dev/api

Quick Reference

Auth Methods

Bearer <jwt> — JWT from login

Bearer vxf_<key> — API key

Response Format

All responses are JSON

Timestamps in ISO 8601 UTC

UUIDs as primary keys

Status Codes

200 OK · 201 Created · 204 No Content

400 Bad Request · 401 Unauthorized

403 Forbidden · 404 Not Found · 500 Error

Errors

{"error": "message"}

Authentication

Voxlancer supports two authentication methods: JWT tokens (from login) and API keys (prefixed vxf_). Pass either in the Authorization header.

Authorization: Bearer <your_token>

Method	Path	Auth
POST	/api/auth/register	No
POST	/api/auth/login	No
GET	/api/auth/me	Yes

Register

POST/api/auth/register— Register a new customer account

Request Body

{
  "email": "user@example.com",
  "password": "yourpassword123",
  "company_name": "My Company"
}

Response

{
  "id": "uuid",
  "email": "user@example.com",
  "balance": "0",
  "status": "pending_review",
  "manual_review_flag": true,
  "created_at": "2026-03-22T10:00:00Z"
}

Login

POST/api/auth/login— Authenticate and receive a JWT token

Request Body

{
  "email": "user@example.com",
  "password": "yourpassword123"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "customer": {
    "id": "uuid",
    "email": "user@example.com",
    "balance": "10.00",
    "status": "active"
  }
}

API Keys

API keys allow programmatic access to your Voxlancer account without using your login credentials. Keys are prefixed with vxf_ and can be assigned granular permissions.

Method	Path	Auth
GET	/api/api-keys	Yes
POST	/api/api-keys	Yes
DELETE	/api/api-keys/:id	Yes

Create API Key

POST/api/api-keys— Generate a new API key

Request Body

{
  "name": "Production Key",
  "permissions": ["campaigns:read", "campaigns:write", "contacts:write"]
}

Response

{
  "id": "uuid",
  "name": "Production Key",
  "key": "vxf_a86655a2b0bbc212acd...",
  "key_prefix": "vxf_vxf_a866",
  "permissions": ["campaigns:read", "campaigns:write"],
  "created_at": "2026-03-22T10:00:00Z"
}

List API Keys

GET/api/api-keys— List all API keys (key value only shown on creation)

Response

[
  {
    "id": "uuid",
    "name": "Production Key",
    "key_prefix": "vxf_vxf_a866",
    "permissions": ["campaigns:read"],
    "created_at": "2026-03-22T10:00:00Z"
  }
]

Revoke API Key

DELETE/api/api-keys/:id— Permanently revoke an API key

Response

204 No Content

Store your key securely

The full key value is only shown once upon creation. Save it immediately — it cannot be retrieved later.

Billing

Method	Path	Auth
GET	/api/billing/balance	Yes
POST	/api/billing/add-credit	Yes
GET	/api/billing/transactions	Yes
GET	/api/billing/usage	Yes

Get Balance

GET/api/billing/balance— Get account balance

Response

{ "balance": "10.00" }

Add Credit

POST/api/billing/add-credit— Add credit to your account

Request Body

{
  "amount": 50.00,
  "stripe_token": "tok_..."
}

Response

{
  "id": "uuid",
  "type": "credit_added",
  "amount": "50.00",
  "balance_after": "60.00",
  "description": "Added $50.00 credit",
  "created_at": "2026-03-22T10:00:00Z"
}

Get Transactions

GET/api/billing/transactions— List account transactions

Response

[
  {
    "id": "uuid",
    "type": "credit_added",
    "amount": "50.00",
    "balance_after": "60.00",
    "description": "Added $50.00 credit",
    "created_at": "2026-03-22T10:00:00Z"
  }
]

Get Usage

GET/api/billing/usage— Get usage statistics

Response

{
  "total_calls": 150,
  "total_minutes": 45.5,
  "total_spent": "0.91"
}

Campaigns

Method	Path	Auth
GET	/api/campaigns	Yes
POST	/api/campaigns	Yes
GET	/api/campaigns/:id	Yes
PUT	/api/campaigns/:id	Yes
DELETE	/api/campaigns/:id	Yes
POST	/api/campaigns/:id/start	Yes
POST	/api/campaigns/:id/pause	Yes
POST	/api/campaigns/:id/resume	Yes
POST	/api/campaigns/:id/stop	Yes
GET	/api/campaigns/:id/stats	Yes
POST	/api/campaigns/:id/retry-failed	Yes

Create Campaign

POST/api/campaigns— Create a new voice campaign

Request Body

{
  "name": "My Campaign",
  "tts_message": "Hello, this is an important message from your healthcare provider.",
  "tts_voice": "en-US",
  "caller_id": "uuid-of-verified-number",
  "tcpa_consent": true,
  "schedule_start": "2026-03-22T10:00:00Z",
  "schedule_end": "2026-03-29T10:00:00Z",
  "calling_hours_start": "09:00",
  "calling_hours_end": "21:00",
  "max_concurrent": 5
}

Response

{
  "id": "uuid",
  "name": "My Campaign",
  "status": "draft",
  "tts_message": "...",
  "tts_voice": "en-US",
  "caller_id": "uuid",
  "total_contacts": 0,
  "created_at": "2026-03-22T10:00:00Z"
}

Campaign Stats

GET/api/campaigns/:id/stats— Get campaign statistics

Response

{
  "campaign_id": "uuid",
  "total_contacts": 100,
  "pending": 0,
  "queued": 0,
  "called": 95,
  "failed": 3,
  "no_answer": 2,
  "opted_out": 0,
  "total_duration_seconds": 1425,
  "total_cost": "0.47",
  "answered_rate": 0.95
}

Campaign Statuses

draft — Created but not startedrunning — Actively callingpaused — Paused mid-campaigncompleted — All contacts processed

Contacts

Method	Path	Auth
GET	/api/campaigns/:id/contacts	Yes
POST	/api/campaigns/:id/contacts/upload	Yes
POST	/api/campaigns/:id/contacts	Yes
DELETE	/api/campaigns/:id/contacts/:contact_id	Yes

Upload Contacts (CSV)

POST/api/campaigns/:id/contacts/upload— Upload contacts via CSV file

Request Body

Content-Type: multipart/form-data
file: <CSV file>

CSV format:
phone_number
+15551234567
+15559876543

Response

{
  "uploaded": 150,
  "duplicates_skipped": 2,
  "invalid_skipped": 1,
  "contacts": [...]
}

Add Single Contact

POST/api/campaigns/:id/contacts— Add one contact to a campaign

Request Body

{ "phone_number": "+15551234567" }

Response

{
  "id": "uuid",
  "campaign_id": "uuid",
  "phone_number": "+15551234567",
  "status": "pending",
  "attempts": 0,
  "created_at": "2026-03-22T10:00:00Z"
}

Phone Number Format

All phone numbers must be in E.164 format (e.g., +15551234567).

Caller IDs

Manage the phone numbers used as the caller ID for outbound campaigns.

Method	Path	Auth
GET	/api/caller-ids	Yes
POST	/api/caller-ids	Yes
DELETE	/api/caller-ids/:id	Yes

Add Caller ID

POST/api/caller-ids— Register a new caller ID number

Request Body

{ "phone_number": "+15551234567" }

Response

{
  "id": "uuid",
  "customer_id": "uuid",
  "phone_number": "+15551234567",
  "verified": false,
  "created_at": "2026-03-22T10:00:00Z"
}

Text-to-Speech

Method	Path	Auth
GET	/api/tts/voices	Yes
POST	/api/tts/preview	Yes

List Voices

GET/api/tts/voices— Get available TTS voices

Response

{ "voices": ["en-US", "en-GB", "en-AU", "en"] }

Preview TTS

POST/api/tts/preview— Generate TTS audio for preview

Request Body

{
  "text": "Hello, this is a test of the Voxlancer text to speech system.",
  "voice": "en-US"
}

Response

Content-Type: audio/wav

<binary WAV audio data>