CDR API: Retrieve Call Detail Records Programmatically
Access Your Call Data with the Simple Telecom CDR API — Billing, Analytics & Attribution
Key CDR API Features
- Retrieve paginated call detail records for any service number
- Filter by custom date ranges with YYYY-MM-DD format
- Access call duration, source number, destination, and cost data
- Sort results by start time in ascending or descending order
- Query across multiple calendar months automatically
What Is the CDR API?
The Call Detail Records (CDR) API is a RESTful endpoint that gives you programmatic access to your call data. Every call made to your Simple Telecom service numbers — whether 1300, 1800, or CTN — generates a detailed record containing the call’s start and end time, duration, the caller’s number, the destination number, and the cost charged to your account. The CDR API lets you retrieve this data programmatically for billing reconciliation, usage analysis, compliance reporting, and marketing attribution.
Records are available within 1–2 minutes of a call completing and being priced. This near-real-time access means you can build dashboards, trigger automated workflows, and generate reports without waiting for periodic data exports. The API returns data in JSON format, making it easy to integrate with analytics platforms, custom dashboards, and business intelligence tools.
Australian businesses use the CDR API to track call volumes across marketing campaigns, monitor staff performance, reconcile phone bills, and understand customer calling patterns. The data is comprehensive enough for sophisticated analysis while being simple enough to use in basic scripts and spreadsheets.
Querying CDR Data: Parameters and Options
The CDR API endpoint GET /api/cdrs accepts several query parameters to help you find exactly the data you need. The service_number parameter is required — you must specify which of your service numbers to retrieve records for. This ensures you only see data relevant to the number you’re analysing.
Date filtering is handled with start_date and end_date parameters in YYYY-MM-DD format. The default date range is the last 30 days if you don’t specify a range. The API supports queries spanning multiple calendar months, automatically querying the relevant monthly data tables. This is particularly useful for end-of-month billing reconciliation or monthly performance reporting.
For large datasets, use the page and page_size parameters for pagination. You can retrieve up to 100 records per page, with a default of 50. The order parameter lets you sort results by start time in ascending or descending order. The response includes a meta object with total records, current page, page size, and total pages — so you can easily navigate through large result sets.
Understanding CDR Response Data
Each CDR record returned by the API contains rich data about a single call. The cdr_id is a unique identifier for each call record. The start_time and end_time are in ISO 8601 UTC format, giving you precise timing information. duration_sec tells you the call length in seconds — useful for calculating average handle time or total talk time per agent.
The source_number field shows the caller’s number, which is invaluable for lead tracking and identifying repeat callers. The service_number confirms which of your numbers received the call — essential if you’re tracking multiple campaigns or departments. The destination field shows the number the call was forwarded to. If the call was not answered or didn’t connect, this field will be empty.
The cost field shows the amount charged to your account in AUD, returned as a string with 4 decimal places for precision. This data is critical for cost analysis, per-campaign ROI calculations, and billing reconciliation. The meta object in the response also echoes back the service number, start date, and end date used in your query, making it easy to track what parameters produced each result set.
Using CDR Data for Marketing Attribution
One of the most powerful applications of the CDR API is marketing attribution. By assigning unique 1300 or 1800 numbers to different marketing channels, you can use the CDR API to determine exactly which campaigns drive phone calls. For example, use one number for Google Ads, another for Facebook, and a third for radio advertising. Then query the CDR API for each number to compare call volumes, durations, and costs.
Beyond simple volume tracking, CDR data enables sophisticated attribution analysis. You can calculate cost-per-lead by dividing campaign spend by call volume, identify which channels drive the longest calls (indicating higher engagement), and track call patterns over time to understand seasonal trends. This data can be fed directly into your CRM or analytics platform for automated reporting.
For marketing operations teams, the CDR API eliminates manual call log collection. Instead of having staff manually log each call, you can pull the data programmatically and match it to campaign records automatically. This saves time, reduces errors, and provides a complete, auditable record of every call your marketing generates.
Code Examples: Getting Started with the CDR API
Getting started with the CDR API is straightforward. Here’s a basic example using cURL to retrieve the last 30 days of CDR data for a service number:
curl -X GET "https://api.simpletelecom.com.au/v1/api/cdrs?service_number=1300858751" -H "Authorization: Bearer YOUR_TOKEN"
For a specific date range with pagination: curl -X GET "https://api.simpletelecom.com.au/v1/api/cdrs?service_number=1300858751&start_date=2026-05-01&end_date=2026-05-31&page=1&page_size=100" -H "Authorization: Bearer YOUR_TOKEN"
In JavaScript, using fetch: const response = await fetch(baseUrl + '/api/cdrs?' + params, { headers: { 'Authorization': Bearer ' + token } }); const { data, meta } = await response.json();
Full code examples for PHP, JavaScript, and cURL are available in the official API documentation.
Error Handling and Best Practices
When working with the CDR API, understanding error responses is essential. A 400 error with code missing_parameter means the service_number was not provided. invalid_date_format means your date doesn’t match YYYY-MM-DD. invalid_date_range means the start date is after the end date. unauthorized (401) means your token is missing, invalid, or expired. method_not_allowed (405) means you’re not using GET. too_many_requests (429) means you’ve exceeded the rate limit.
For best results, always check the rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and implement retry logic with backoff. Use pagination for large result sets rather than requesting all records at once. Validate date formats before sending requests, and store your API token securely — never expose it in client-side code or public repositories.
Frequently Asked Questions
Frequently Asked Questions About the CDR API
How quickly are CDR records available after a call ends?
Records typically appear within 1–2 minutes of a call completing and being priced. Calls in progress or recently completed may not yet appear in the API results.
Can I query CDRs for multiple service numbers at once?
The API requires a single service_number per query. To retrieve data for multiple numbers, make separate requests for each service number. You can automate this by first calling the Services API to get all your numbers, then querying CDRs for each one.
What happens if the destination field is empty?
An empty destination means the call did not connect to a forwarding number. This can happen if the caller hung up before the call was answered, if no forwarding destination was reached, or if the call failed for another reason.
How far back can I query CDR data?
There is no hard limit on how far back you can query, but very old data may be in archived storage and take longer to retrieve. For most accounts, data is available for the current and previous months.
Can I export CDR data to a CSV or spreadsheet?
The API returns JSON data. You can write a simple script to convert the JSON response to CSV format, or use tools like jq to transform the data for spreadsheet import.
Our CDR API gives you complete visibility into your call patterns, helping you optimise your business communications strategy. Whether you’re managing a 1300 Number Lookup to track incoming calls, routing calls via 1300 Number To Mobile forwarding, or exploring how to 1800 Number How To Get started, detailed call records are essential. Access programmatic call data to monitor performance, improve your Complaint Handling Process, and ensure every customer interaction strengthens your professional national presence.
