Skip to main content

Making Your First Request

This guide walks you through making your first API request to CallCov, from authentication to receiving your analysis results.

Before You Start​

Make sure you have:

  • ✅ Created a CallCov account
  • ✅ Verified your email
  • ✅ Obtained an API key or access token
  • ✅ A sample call recording file

If you haven't completed these steps, see the Quickstart Guide.

Base URL​

All API requests are made to:

https://api.callcov.com/api/v1

Request Format​

CallCov uses RESTful API principles:

  • Protocol: HTTPS only
  • Format: JSON for request/response bodies
  • Authentication: Bearer token in Authorization header
  • Content-Type: application/json (or multipart/form-data for file uploads)

Example: Submit an Analysis​

Let's analyze a call recording step by step.

cURL Example​

curl -X POST https://api.callcov.com/api/v1/analysis/ \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/recordings/call-001.wav",
    "agent_id": "agent_john_doe",
    "contact_id": "customer_12345",
    "webhook_url": "https://your-app.com/webhooks/analysis"
  }'

Python Example​

import requests

# Your API credentials
API_KEY = "sk_live_abc123..."
BASE_URL = "https://api.callcov.com/api/v1"

# Prepare the request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "audio_url": "https://example.com/recordings/call-001.wav",
    "agent_id": "agent_john_doe",
    "contact_id": "customer_12345",
    "webhook_url": "https://your-app.com/webhooks/analysis"
}

# Make the request
response = requests.post(
    f"{BASE_URL}/analysis/",
    headers=headers,
    json=payload
)

# Handle the response
if response.status_code == 201:
    analysis = response.json()
    print(f"✅ Analysis created: {analysis['id']}")
    print(f"Status: {analysis['status']}")
else:
    print(f"❌ Error: {response.status_code}")
    print(response.json())

Node.js Example​

const axios = require('axios');

const API_KEY = 'sk_live_abc123...';
const BASE_URL = 'https://api.callcov.com/api/v1';

async function submitAnalysis() {
  try {
    const response = await axios.post(
      `${BASE_URL}/analysis/`,
      {
        audio_url: 'https://example.com/recordings/call-001.wav',
        agent_id: 'agent_john_doe',
        contact_id: 'customer_12345',
        webhook_url: 'https://your-app.com/webhooks/analysis'
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('✅ Analysis created:', response.data.id);
    console.log('Status:', response.data.status);
  } catch (error) {
    console.error('❌ Error:', error.response.status);
    console.error(error.response.data);
  }
}

submitAnalysis();

Response Structure​

Success Response (201 Created)​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1642248000,
  "status": "processing",
  "livemode": true,
  "call": {
    "agent_id": "agent_john_doe",
    "contact_id": "customer_12345"
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov/...",
    "duration_seconds": null,
    "format": "wav",
    "file_size": null
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "processing_time_ms": null,
    "version": "1.0.0"
  }
}

Error Response (400 Bad Request)​

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "audio_url"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Checking Analysis Status​

Analyses are processed asynchronously. Check the status with:

curl -X GET https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_abc123..."

Status Values​

StatusDescription
processingAnalysis is in progress
completedAnalysis finished successfully
failedAnalysis encountered an error

Polling for Results​

import time
import requests

def wait_for_analysis(analysis_id, api_key, max_wait=300):
    """Poll for analysis completion (max 5 minutes)"""
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.callcov.com/api/v1/analysis/{analysis_id}"

    start_time = time.time()
    while time.time() - start_time < max_wait:
        response = requests.get(url, headers=headers)
        analysis = response.json()

        if analysis['status'] == 'completed':
            print("✅ Analysis complete!")
            return analysis
        elif analysis['status'] == 'failed':
            print("❌ Analysis failed:", analysis.get('error_message'))
            return None

        print(f"⏳ Status: {analysis['status']}... waiting")
        time.sleep(10)  # Poll every 10 seconds

    print("⏱️ Timeout waiting for analysis")
    return None

# Usage
analysis_id = "550e8400-e29b-41d4-a716-446655440000"
result = wait_for_analysis(analysis_id, "sk_live_abc123...")

Instead of polling, use webhooks for real-time notifications:

# When creating analysis, include webhook_url
payload = {
    "audio_url": "https://example.com/recordings/call-001.wav",
    "agent_id": "agent_john_doe",
    "contact_id": "customer_12345",
    "webhook_url": "https://your-app.com/webhooks/analysis"  # ← Your webhook endpoint
}

Your webhook will receive:

{
  "event": "analysis.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "results": { ... }
  }
}

Learn more in the Webhooks Guide.

Common Issues​

401 Unauthorized​

{"detail": "Invalid authentication credentials"}

Solution: Check your API key is correct and included in the Authorization header.

400 Bad Request​

{"detail": "audio_url is required"}

Solution: Ensure all required fields are included in your request.

422 Unprocessable Entity​

{"detail": "Invalid audio file format"}

Solution: Check that your audio file is in a supported format (WAV, MP3, etc.).

Rate Limits​

CallCov enforces rate limits to ensure service quality:

  • Default: 100 requests per minute
  • Analysis submissions: 20 per minute

Rate limit info is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248060

Next Steps​

Now that you've made your first request, explore: