Vobiz Logo
Vobiz
|API Documentation
Console

Call Detail Records (CDR)

Track and analyze call records with comprehensive CDR data. Includes caller/destination info, duration, timestamps, hangup causes, and billing details for every call processed through your SIP trunks.

List Call Detail Records

GET/api/v1/account/{accountId}/cdr?page=1&per_page=50

Retrieve paginated call detail records for the account.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Query comprehensive call history with powerful filtering and pagination capabilities for billing reconciliation, usage analysis, and fraud detection. Filter records by date range, call direction (inbound/outbound), trunk ID, call status, or specific caller/callee numbers. The response includes pagination metadata and usage summary statistics showing total calls, answered calls, failed calls, cumulative duration, and total costs. Maximum date range is 90 days per query with configurable result limits up to 1000 records.

Response Components
  • CDR array with detailed call information: participants, timestamps, duration, costs, status
  • Pagination metadata: total count, current limit/offset, hasMore flag for navigation
  • Summary statistics: aggregated totals for calls, duration, costs across filtered results
Common Use Cases
  • Monthly billing reconciliation by filtering date ranges and summing call costs
  • Call quality monitoring by analyzing failed calls, no-answer rates, and hangup causes
  • Fraud detection through pattern analysis of unusual call volumes or destinations

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination. Default: 1
per_pageintegerNoRecords per page. Default: 50, Maximum: 100

Response Example

Success Response (200 OK)
{
  "status": "success",
  "data": {
    "cdrs": [
      {
        "id": "CDR_9a8b7c6d5e4f",
        "callId": "7f8e9d2c-1a3b-4c5d-6e7f-8g9h0i1j2k3l",
        "direction": "outbound",
        "caller": "+14155551234",
        "callee": "+12125559876",
        "trunkId": "TRK_8f9e0a1b2c3d",
        "trunkName": "Production Trunk",
        "startTime": "2025-10-12T14:30:00.000Z",
        "answerTime": "2025-10-12T14:30:05.000Z",
        "endTime": "2025-10-12T14:35:12.000Z",
        "duration": 312,
        "billableSeconds": 312,
        "status": "answered",
        "hangupCause": "NORMAL_CLEARING",
        "hangupBy": "caller",
        "cost": 156,
        "currency": "USD",
        "ratePerMinute": 30
      },
      {
        "id": "CDR_3c4d5e6f7g8h",
        "callId": "2a3b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
        "direction": "inbound",
        "caller": "+16505551111",
        "callee": "+14155551234",
        "trunkId": "TRK_8f9e0a1b2c3d",
        "trunkName": "Production Trunk",
        "startTime": "2025-10-12T13:15:00.000Z",
        "answerTime": null,
        "endTime": "2025-10-12T13:15:08.000Z",
        "duration": 0,
        "billableSeconds": 0,
        "status": "no_answer",
        "hangupCause": "NO_ANSWER",
        "hangupBy": "system",
        "cost": 0,
        "currency": "USD",
        "ratePerMinute": 30
      }
    ],
    "pagination": {
      "total": 1847,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    },
    "summary": {
      "totalCalls": 1847,
      "answeredCalls": 1523,
      "failedCalls": 324,
      "totalDuration": 45678,
      "totalCost": 22839,
      "currency": "USD"
    }
  }
}

Search CDRs

GET/api/v1/account/{accountId}/cdr/search?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z&page=1&per_page=50

Advanced CDR search with date filters and pagination. Search by timestamp range with more precise filtering.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Perform advanced call detail record searches with precise timestamp filtering and pagination controls. Unlike the basic list endpoint, the search endpoint accepts ISO 8601 timestamp ranges with timezone and time-of-day precision, enabling targeted queries for specific hours, days, or custom time windows. Results are paginated with page number and per-page controls for easier navigation through large result sets. Use this endpoint when you need timestamp-based filtering beyond simple date ranges or require more granular control over result pagination.

Search Capabilities
  • ISO 8601 timestamp filtering with timezone support (e.g., 2024-01-01T00:00:00Z)
  • Page-based pagination instead of offset/limit for easier navigation
  • Same comprehensive CDR data as list endpoint with pagination metadata
Common Use Cases
  • Querying calls during specific hours (e.g., after-hours calls, peak time analysis)
  • Searching across month boundaries with precise start/end timestamps
  • Building paginated search interfaces with page number navigation

Query Parameters

ParameterTypeRequiredDescription
start_datestringNoStart timestamp in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
end_datestringNoEnd timestamp in ISO 8601 format (e.g., 2024-01-31T23:59:59Z)
pageintegerNoPage number for pagination. Default: 1
per_pageintegerNoRecords per page. Default: 50, Maximum: 100

Response Example

Success Response (200 OK)
{
  "status": "success",
  "data": {
    "cdrs": [
      {
        "id": "CDR_9a8b7c6d5e4f",
        "callId": "7f8e9d2c-1a3b-4c5d-6e7f-8g9h0i1j2k3l",
        "direction": "outbound",
        "caller": "+14155551234",
        "callee": "+12125559876",
        "trunkId": "TRK_8f9e0a1b2c3d",
        "trunkName": "Production Trunk",
        "startTime": "2024-01-15T14:30:00.000Z",
        "answerTime": "2024-01-15T14:30:05.000Z",
        "endTime": "2024-01-15T14:35:12.000Z",
        "duration": 312,
        "billableSeconds": 312,
        "status": "answered",
        "hangupCause": "NORMAL_CLEARING",
        "cost": 156,
        "currency": "USD"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 1847,
      "total_pages": 37
    }
  }
}

CDR Fields Reference

Call Identifiers

  • id - Unique CDR record ID
  • callId - Unique call session ID (UUID)
  • trunkId - SIP trunk used for the call
  • accountId - Account that owns the call

Call Participants

  • caller - Calling party number (E.164 format)
  • callee - Called party number (E.164 format)
  • direction - inbound or outbound

Timestamps

  • startTime - Call initiation (SIP INVITE received)
  • answerTime - Call answered (200 OK received), null if not answered
  • endTime - Call termination (BYE received)
  • ringDuration - Seconds between start and answer
  • duration - Total call duration in seconds (answer to end)

Call Status

  • status - answered, no_answer, busy, failed, cancelled
  • hangupCause - SIP reason code (see Hangup Causes below)
  • hangupBy - caller, callee, or system
  • sipCode - SIP response code (200, 404, 486, etc.)

Billing

  • cost - Total call cost in cents
  • currency - Currency code (USD, EUR, etc.)
  • ratePerMinute - Rate charged in cents per minute
  • billableSeconds - Seconds used for billing calculation

Common Hangup Causes

Each CDR includes a hangup cause that indicates why the call ended. These map to standard SIP response codes.

NORMAL_CLEARING

Normal call termination - one party hung up

SIP Code: 200 OK or 487 Request Terminated

NO_ANSWER

Call not answered within timeout period (usually 60s)

SIP Code: 408 Request Timeout

USER_BUSY

Called party is busy on another call

SIP Code: 486 Busy Here

CALL_REJECTED

Call actively declined by the callee

SIP Code: 603 Decline

INVALID_NUMBER

Destination number doesn't exist or is invalid

SIP Code: 404 Not Found

NETWORK_ERROR

Network or routing failure in carrier infrastructure

SIP Code: 503 Service Unavailable

ORIGINATOR_CANCEL

Caller cancelled call before it was answered

SIP Code: 487 Request Terminated

INSUFFICIENT_FUNDS

Account balance too low to complete call

SIP Code: 402 Payment Required

TEMPORARILY_UNAVAILABLE

Callee device is registered but not reachable

SIP Code: 480 Temporarily Unavailable

UNALLOCATED_NUMBER

Number is not assigned or has been disconnected

SIP Code: 410 Gone

Duration vs Billable Seconds

Understanding the difference between duration and billableSeconds is crucial for accurate billing.

Duration

Total time from when the call was answered (200 OK) until it ended (BYE received).

Formula:

duration = endTime - answerTime

If call was never answered, duration = 0

Billable Seconds

Rounded duration used for billing calculations. Typically rounded up to the nearest billing increment (6 or 60 seconds).

Example:

duration: 312s
billableSeconds: 312s (rounded to 6s increments)

Minimum billable: usually 6 or 60 seconds

Billing Example

• Call duration: 312 seconds (5 minutes 12 seconds)

• Billable seconds: 312 seconds (rounded to nearest 6s)

• Rate: $0.30 per minute

• Cost calculation: (312 / 60) × $0.30 = $1.56

Common Use Cases

Billing Reconciliation

Export CDRs monthly to reconcile charges with customer invoices. Filter by account and date range, then sum billable costs.

Monthly Billing Query
GET /api/v1/account/MA_2210JXXN/cdr/export?format=csv&start_date=2025-10-01&end_date=2025-10-31
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Call Quality Monitoring

Track failed calls, no-answer rates, and average call duration to identify network issues or routing problems.

Failed Calls Analysis
GET /api/v1/account/MA_2210JXXN/cdr?status=failed&start_date=2025-10-12&end_date=2025-10-12
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Customer Analytics

Analyze call patterns: peak hours, most called numbers, average call duration, inbound vs outbound ratios.

Outbound Calls for Analysis
GET /api/v1/account/MA_2210JXXN/cdr?direction=outbound&start_date=2025-10-01&end_date=2025-10-12&limit=1000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Fraud Detection

Monitor unusual calling patterns: sudden spikes in call volume, calls to expensive international destinations, or short-duration mass dialing.

Recent High-Volume Activity
GET /api/v1/account/MA_2210JXXN/cdr?start_date=2025-10-12&limit=100
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Error Responses

400 Bad Request

Invalid query parameters or date format.

Error Response
{
  "error": {
    "code": "INVALID_DATE_FORMAT",
    "message": "start_date must be in YYYY-MM-DD format",
    "field": "start_date",
    "value": "2025/10/12"
  }
}

401 Unauthorized

Missing or invalid JWT Bearer token.

Error Response
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

404 Not Found

Specific CDR record not found.

Error Response
{
  "error": {
    "code": "CDR_NOT_FOUND",
    "message": "No CDR found with ID: CDR_invalid123",
    "cdrId": "CDR_invalid123"
  }
}

422 Unprocessable Entity

Date range too large (exceeds maximum allowed period).

Error Response
{
  "error": {
    "code": "DATE_RANGE_TOO_LARGE",
    "message": "Date range cannot exceed 90 days for list queries",
    "maxDays": 90,
    "requestedDays": 180
  }
}

429 Too Many Requests

Rate limit exceeded. Retry after specified time.

Error Response
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 60 seconds",
    "retryAfter": 60,
    "limit": 100,
    "window": "1 minute"
  }
}
Phone Numbers
Health & Monitoring