Vox · Voice AI

Vox is Cloove’s AI voice platform. Use it to place AI-powered outbound calls, review call history, and read the numbers and agents available to your business.

All Vox endpoints share the prefix /v1/vox and authenticate with an API key.

Endpoint	Scope
`GET /v1/vox/health`	`vox:read`
`GET /v1/vox/calls`	`vox:calls:read`
`POST /v1/vox/calls`	`vox:calls:create`
`GET /v1/vox/numbers`	`vox:numbers:read`
`GET /v1/vox/agents`	`vox:agents:read`

Health check

Confirm a key is valid and see which business and environment it’s bound to.


GET /v1/vox/health


{
  "message": "Vox API ready",
  "data": {
    "businessId": "b1a2c3d4-...",
    "environment": "test",
    "keyId": "k1a2c3d4-..."
  }
}

List calls


GET /v1/vox/calls

Returns a paginated list of calls for your business, newest first.

Query parameters

Parameter	Type	Description
`direction`	string	Filter by `inbound` or `outbound`
`status`	string	Filter by call status (e.g. `completed`, `failed`)
`search`	string	Match against customer name or phone
`page`	number	Page number (default `1`)
`limit`	number	Items per page (default `20`)


{
  "message": "Vox calls retrieved",
  "data": [
    {
      "id": "c1a2b3c4-...",
      "businessId": "b1a2c3d4-...",
      "direction": "outbound",
      "status": "completed",
      "customerPhone": "+2348012345678",
      "customerName": "Ada Lovelace",
      "durationSeconds": 122,
      "startedAt": "2026-01-15T10:00:00.000Z",
      "endedAt": "2026-01-15T10:02:02.000Z",
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20, "totalPages": 1, "hasMore": false }
}

Place an outbound call


POST /v1/vox/calls

Queues an AI-powered outbound call. The call is dialed asynchronously - the response confirms it was accepted, not that it connected. Send an Idempotency-Key (header or idempotency_key field) so a retry never dials twice.

Body

Field	Type	Required	Description
`customer_phone`	string	Yes	Destination number in E.164 (e.g. `+2348012345678`)
`customer_name`	string	No	Used by the agent to personalize the call
`purpose`	string	Yes	Short label for the call’s intent
`context`	string	Yes	Instructions and context for the AI agent
`business_voice_number_id`	uuid	Yes	The number to call from (see List numbers)
`ai_agent_id`	uuid	Yes	The agent to run the call (see List agents)
`idempotency_key`	string	No	Dedupe key; alternative to the `Idempotency-Key` header


{
  "customer_phone": "+2348012345678",
  "customer_name": "Ada Lovelace",
  "purpose": "payment_reminder",
  "context": "Remind the customer about invoice INV-2026-001 for NGN 15,000 due tomorrow.",
  "business_voice_number_id": "n1a2b3c4-...",
  "ai_agent_id": "a1a2b3c4-..."
}

Response 201 Created


{
  "message": "Vox outbound call queued",
  "data": {
    "id": "r1a2b3c4-...",
    "businessId": "b1a2c3d4-...",
    "customerPhone": "+2348012345678",
    "customerName": "Ada Lovelace",
    "purpose": "payment_reminder",
    "status": "queued",
    "createdAt": "2026-01-15T10:00:00.000Z"
  }
}

Track call progress with the vox.call.started, vox.call.completed, vox.call.failed, and vox.recording.ready webhooks rather than polling.

List numbers


GET /v1/vox/numbers

Returns the voice numbers assigned to your business.


{
  "message": "Vox numbers retrieved",
  "data": [
    {
      "id": "n1a2b3c4-...",
      "phoneNumber": "+2348012345678",
      "country": "NG",
      "voiceCapable": true,
      "smsCapable": true,
      "status": "active",
      "provider": "telnyx",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

List agents


GET /v1/vox/agents

Returns the AI agent configurations available to your business.


{
  "message": "Vox AI agents retrieved",
  "data": [
    {
      "id": "a1a2b3c4-...",
      "name": "Support Agent",
      "language": "en",
      "voiceProvider": "openai_realtime",
      "voiceId": "alloy",
      "persona": "Friendly and professional support representative",
      "isDefault": false,
      "status": "active",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}