The instructions below are intended for users on OTHOS TELECOM phone system ONLY, and may not be applicable for devices on other platforms. For more information on using our services, please visit our website www.othos.co.za or give us a call on 021 673 6801.
# CDR API - Client Documentation
A REST API for accessing Call Detail Records (CDRs) with authentication, rate limiting, and compliance
features.
## Base URL
**Production:** `https://api.ocs.othos.co.za`
## Authentication
The API uses JWT (JSON Web Token) authentication. You'll need an API key to obtain a token.
### Getting Your API Key
Contact your administrator to obtain your unique API key (UUID format). Each API key is associated with
a specific domain and grants access only to CDR data for that domain.
## API Endpoints
### 1. Authentication
#### Login
Obtain a JWT token using your API key.
**Endpoint:** `POST /auth/login`
**Request:**
```bash
curl -X POST "https://api.ocs.othos.co.za/auth/login" \
-H "Content-Type: application/json" \
-d '{"api_key": "your-api-key-uuid-here"}'
```
**Response (Success - 200):**
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"name": "Your Company Name"
}
```
**Response (Error - 401):**
```json
{
"error": "Invalid API key"
}
```
**Notes:**
- The token expires in 30 minutes by default
- Store the token securely and use it in subsequent API calls
- The API key must be a valid UUID format
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa---
### 2. CDR Data
#### List CDRs
Retrieve CDR records with filtering and pagination.
**Endpoint:** `GET /api/cdr`
**Required Headers:**
- `Authorization: Bearer <your-jwt-token>`
**Required Parameters:**
- `start_date` - Start date in YYYY-MM-DD format
- `end_date` - End date in YYYY-MM-DD format
**Optional Parameters:**
- `start_time` - Start time in HH:MM:SS format
- `end_time` - End time in HH:MM:SS format
- `caller_number` - Partial match for caller number
- `destination_number` - Partial match for destination number
- `limit` - Number of records to return (1-1000, default: 100)
- `offset` - Number of records to skip for pagination (default: 0)
**Example Request:**
```bash
curl -X GET "https://api.ocs.othos.co.za/api/cdr?start_date=2024-01-01&end_date=2024-01-
31&limit=50" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Example with Time Range:**
```bash
curl -X GET "https://api.ocs.othos.co.za/api/cdr?start_date=2024-01-15&end_date=2024-01-
15&start_time=09:00:00&end_time=17:00:00" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Example with Phone Number Filter:**
```bash
curl -X GET "https://api.ocs.othos.co.za/api/cdr?start_date=2024-01-01&end_date=2024-01-
31&caller_number=+27" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Response (Success - 200):**
```json
{
"data": [
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa{
"xml_cdr_uuid": "12345678-1234-5678-9012-123456789012",
"caller_id_number": "+27123456789",
"destination_number": "+27987654321",
"start_stamp": "2024-01-15T10:30:00.000Z",
"duration": 180,
"billsec": 175,
"has_recording: true"
}
],
"pagination": {
"limit": 50,
"offset": 0
}
}
```
**Response Headers:**
- `X-RateLimit-Limit: 100` - Your hourly rate limit
- `X-RateLimit-Remaining: 95` - Remaining requests in current hour
---
#### Download Recording
Get a temporary download URL for a call recording.
**Endpoint:** `GET /api/cdr/download`
**Required Headers:**
- `Authorization: Bearer <your-jwt-token>`
**Required Parameters:**
- `uuid` - The CDR UUID from the list endpoint
**Example Request:**
```bash
curl -X GET "https://api.ocs.othos.co.za/api/cdr/download?uuid=12345678-1234-5678-9012-
123456789012" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Response (Success - 200):**
```json
{
"download_url": "https://recordings.s3.af-south-1.amazonaws.com/...",
"expires_in": 300,
"recording_name": "12345678-1234-5678-9012-123456789012.mp3",
"uuid": "12345678-1234-5678-9012-123456789012"
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa}
```
**Download the File:**
```bash
# Use the download_url from the previous response
curl -o "recording.mp3" "https://recordings.s3.af-south-1.amazonaws.com/..."
```
**Notes:**
- The download URL expires in 5 minutes (300 seconds)
- You can only download recordings for CDRs that belong to your domain
- The recording file format is typically MP3 or WAV
---
### 3. Health Check
#### System Health
Check the API system health status.
**Endpoint:** `GET /api/health`
**Example Request:**
```bash
curl -X GET "https://api.ocs.othos.co.za/api/health"
```
**Response (Healthy - 200):**
```json
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00.000Z",
"checks": {
"secrets": { "status": "ok" },
"database": { "status": "ok" },
"redis": { "status": "ok" }
}
}
```
---
## Rate Limiting
- **Limit:** 100 requests per hour per API key
- **Headers:** Rate limit information is included in response headers:
- `X-RateLimit-Limit` - Your hourly limit
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa- `X-RateLimit-Remaining` - Remaining requests in current hour
- `X-RateLimit-Reset` - Unix timestamp when the limit resets
**Rate Limit Exceeded Response (429):**
```json
{
"error": "Rate limit exceeded"
}
```
## Data Compliance
### POPIA Compliance
_url- **Date Range Limit:** Maximum date range is 31 days per query
- **Domain Isolation:** You can only access CDR data for your assigned domain
## Complete Workflow Example
Here's a complete example of authenticating and retrieving CDR data:
```bash
# Step 1: Set your API base URL
export API_BASE="https://api.ocs.othos.co.za"
# Step 2: Login and get token
RESPONSE=$(curl -s -X POST "$API_BASE/auth/login" \
-H "Content-Type: application/json" \
-d '{"api_key": "your-api-key-uuid-here"}')
# Extract token from response
TOKEN=$(echo $RESPONSE | grep -o '"token":"[^"]*' | cut -d'"' -f4)
# Step 3: Query CDRs
curl -X GET "$API_BASE/api/cdr?start_date=2024-01-01&end_date=2024-01-31&limit=10" \
-H "Authorization: Bearer $TOKEN"
# Step 4: Download a recording (replace with actual UUID)
curl -X GET "$API_BASE/api/cdr/download?uuid=12345678-1234-5678-9012-123456789012" \
-H "Authorization: Bearer $TOKEN"
```
## Error Responses
### Common Error Codes
**400 Bad Request**
```json
{
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa"error": "Invalid date range"
}
```
```json
{
}
```
```json
{
}
```
```json
{
}
```
"error": "Date range too large (max 31 days)"
"error": "Current day data not available due to POPIA compliance"
"error": "Invalid request parameters"
**401 Unauthorized**
```json
{
"error": "Unauthorized"
}
```
```json
{
"error": "Invalid API key"
}
```
```json
{
"error": "Invalid token"
}
```
**404 Not Found**
```json
{
}
```
"error": "CDR not found or access denied"
**429 Too Many Requests**
```json
{
"error": "Rate limit exceeded"
}
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa```
**500 Internal Server Error**
```json
{
"error": "Internal server error"
}
```
## Data Fields Reference
### CDR Record Fields
| Field | Type | Description |
|-------|------|-------------|
| xml_cdr_uuid | string | Unique identifier for the CDR record |
| caller_id_number | string | The caller's phone number |
| destination_number | string | The destination phone number |
| start_stamp | string | Call start time (ISO 8601 format) |
| duration | number | Total call duration in seconds |
| billsec | number | Billable seconds (actual talk time) |
| string | URL to the call recording (for convenience) |
### Query Parameters Validation
| Parameter | Format | Required | Notes |
|-----------|--------|----------|-------|
| start_date | YYYY-MM-DD | Yes | Cannot be current day |
| end_date | YYYY-MM-DD | Yes | Must be >= start_date, max 31 days from start_date |
| start_time | HH:MM:SS | No | 24-hour format |
| end_time | HH:MM:SS | No | 24-hour format |
| caller_number | string | No | Partial matching supported |
| destination_number | string | No | Partial matching supported |
| limit | number | No | 1-1000, default 100 |
| offset | number | No | For pagination, default 0 |
## Best Practices
1. **Token Management:** Always check token expiry and re-authenticate when necessary
2. **Rate Limiting:** Monitor rate limit headers and implement appropriate delays
3. **Date Ranges:** Keep date ranges as narrow as possible for better performance
4. **Pagination:** Use pagination for large result sets
5. **Error Handling:** Always check for error responses and handle them appropriately
6. **Security:** Never log or expose JWT tokens in your application logs
T: 021 673 6801 | E: contact@othos.co.za | W: www.othos.co.za
A: Othos Telecom, Inospace Office - Unit 32, 20 Cumberland Drive Paarden Eiland, Cape Town, 7405, South Africa
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article