Voice Call Logs

Voice call logging is essential for monitoring telecommunications activity and compliance requirements. On this page, we will dive into the voice call logging endpoints you can use to retrieve and analyze call records programmatically. We will look at how to fetch call logs with filtering and export functionality.

The voice call log model

The voice call log model contains detailed information about individual call records, including participants, duration, cost calculations, and provider information.

Properties

Name
log_id
Type
uuid
Description
Unique identifier for the voice call log entry.
Name
virtual_number_id
Type
uuid
Description
The virtual number used for the call.
Name
customer_id
Type
uuid
Description
Customer identifier owning the call record.
Name
call_direction
Type
string
Description
Call direction: "inbound" or "outbound".
Name
caller_number
Type
string
Description
The phone number that initiated the call.
Name
called_number
Type
string
Description
The phone number that received the call.
Name
call_start_time
Type
timestamp
Description
Call start timestamp.
Name
call_end_time
Type
timestamp
Description
Call end timestamp (nullable).
Name
call_duration_seconds
Type
integer
Description
Call duration in seconds (nullable).
Name
call_status
Type
string
Description
Call status (e.g., "completed", "busy", "no-answer", "failed").
Name
provider_call_id
Type
string
Description
Provider's unique identifier for the call (nullable).
Name
cost_per_minute
Type
decimal
Description
Cost per minute for the call (nullable).
Name
total_cost
Type
decimal
Description
Total calculated cost for the call (nullable).
Name
currency
Type
string
Description
Currency for cost calculations (nullable).
Name
provider_name
Type
string
Description
Name of the telecommunications provider (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp.
Name
updated_at
Type
timestamp
Description
Last record update timestamp.

GET/customers/{customerSlug}/logs/voice

List voice call logs

This endpoint allows you to retrieve voice call logs for your customer account with comprehensive filtering and sorting options. By default, a maximum of ten records are shown per page.

Optional attributes

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of logs per page (default: 10, min: 1, max: 100).
Name
search
Type
string
Description
General search string to filter logs.
Name
virtual_number_id
Type
uuid
Description
Filter by specific virtual number ID.
Name
call_direction
Type
string
Description
Filter by call direction: "inbound" or "outbound".
Name
call_status
Type
string
Description
Filter by call status.
Name
start_date
Type
string
Description
Filter logs from this date (ISO 8601 format).
Name
end_date
Type
string
Description
Filter logs until this date (ISO 8601 format).
Name
sort_by
Type
string
Description
Sort field: "call_start_time", "call_duration_seconds", "total_cost" (default: "call_start_time").
Name
sort_order
Type
string
Description
Sort direction: "asc" or "desc" (default: "desc").

Request

GET

/logs/voice

curl -G https://api.xnumbers.io/customers/acme-corp/logs/voice \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10 \
  -d call_direction=inbound \
  -d start_date=2024-01-01 \
  -d sort_by=call_start_time \
  -d sort_order=desc

Response

{
  "data": [
    {
      "log_id": "12345678-1234-1234-1234-123456789abc",
      "virtual_number_id": "87654321-4321-4321-4321-210987654321",
      "customer_id": "11111111-1111-1111-1111-111111111111",
      "call_direction": "inbound",
      "caller_number": "+15551234567",
      "called_number": "+12125551234",
      "call_start_time": "2024-01-15T10:30:00.000Z",
      "call_end_time": "2024-01-15T10:35:00.000Z",
      "call_duration_seconds": 300,
      "call_status": "completed",
      "provider_call_id": "prov_call_789123",
      "cost_per_minute": 0.02,
      "total_cost": 0.10,
      "currency": "USD",
      "provider_name": "TeleProvider Inc",
      "created_at": "2024-01-15T10:35:30.000Z",
      "updated_at": "2024-01-15T10:35:30.000Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

GET/customers/{customerSlug}/logs/voice/export

Export voice call logs

This endpoint allows you to export voice call logs as a CSV file. The export includes all the same filtering options as the list endpoint but returns the data in CSV format for download.

Optional attributes

All the same query parameters from the list endpoint are supported for filtering the exported data.

Export Format

The CSV export includes all voice call log fields with proper headers and formatting for analysis in spreadsheet applications.

Request

GET

/logs/voice/export

curl -G https://api.xnumbers.io/customers/acme-corp/logs/voice/export \
  -H "Authorization: Bearer {token}" \
  -d call_direction=inbound \
  -d start_date=2024-01-01 \
  -d end_date=2024-01-31 \
  --output voice_call_logs.csv

Returns the CSV file as a download with appropriate headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="voice_call_logs.csv"