> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# API Reference — Voice Tracking

Track voice agent usage directly via our REST API. This is ideal for custom integrations where you prefer not to use our SDKs. Follow the session lifecycle below to ensure accurate tracking and billing.

> **Warning**
>
> **Prerequisite:** Complete the [Voice Agent Setup](/documentation/voice-tracking/voice-agent-setup) before implementing voice tracking.

## Integration Steps

Follow this 6-step sequence to implement a robust voice tracking pipeline.

---

### 1. Create or Get Customer

Before starting a session, ensure your customer exists in Paygent. This endpoint retrieves an existing customer by `externalId` or creates a new one if not found.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/customers/create-or-get' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Customer Name",
    "externalId": "customer-123"
}'
```

---

### 2. Initialize Voice Session

Initialize a unique session for each voice call. Use your own unique `sessionId` (e.g., Call SID or UUID) to link all subsequent tracking events.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/voice/session' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "voice_call_unique_uuid",
    "agentId": "your-voice-agent-id",
    "customerId": "customer-123"
}'
```

---

### 3. Track STT

Track Speech-to-Text usage by providing the audio duration in minutes.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/voice/stt' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "voice_call_unique_uuid",
    "audioMinutes": 0.5,
    "provider": "deepgram",
    "model": "nova-2",
    "plan": "default"
}'
```

---

### 4. Track LLM

Track Large Language Model usage by providing prompt and completion token counts.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/voice/llm' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "voice_call_unique_uuid",
    "provider": "openai",
    "model": "gpt-4o",
    "plan": "default",
    "promptTokens": 1000,
    "completionTokens": 500,
    "cachedTokens": 200
}'
```

---

### 5. Track TTS

Track Text-to-Speech usage by providing the total character count processed.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/voice/tts' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "voice_call_unique_uuid",
    "provider": "amazon-polly",
    "model": "neural",
    "plan": "default",
    "characters": 28000
}'
```

---

### 6. Set Indicator

Finally, set a voice indicator (e.g., call completion) with the total call duration in minutes.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/voice/indicator' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "voice_call_unique_uuid",
    "indicator": "per-minute-call",
    "totalDuration": 0.5
}'
```