API Response Examples

This page provides complete examples of API responses in different states. All examples are auto-generated from our Pydantic schemas, ensuring they match the actual API structure.

Auto-Generated Examples

These examples are generated using make gen-api-examples directly from our source code schemas. This guarantees they reflect the actual API response structure.

Example Scenarios

Completed Analysis - Successful analysis with full results
Processing Analysis - Analysis in progress
Failed Analysis - Analysis that encountered an error
Compliance Violations - Analysis with multiple issues

Completed Analysis

A successful analysis with all compliance checks passed and full quality metrics:

_example-completed.json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "completed",
  "livemode": false,
  "call": {
    "agent_id": "agent_001",
    "contact_id": "customer_12345",
    "duration_ms": 125500,
    "duration_seconds": 125.5
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/550e8400-e29b-41d4-a716-446655440000.wav",
    "size_bytes": 1048576,
    "format": "wav",
    "duration_seconds": 125.5
  },
  "transcript": {
    "text": "Agent: Hello, thank you for calling. How can I help you today?\nCustomer: Hi, I'm having issues with my account...",
    "segments": [
      {
        "speaker": "A",
        "text": "Hello, thank you for calling. How can I help you today?",
        "start": 0.0,
        "end": 3.2
      },
      {
        "speaker": "B",
        "text": "Hi, I'm having issues with my account.",
        "start": 3.5,
        "end": 5.8
      }
    ],
    "language": "en"
  },
  "results": {
    "compliance": {
      "identity_verification": {
        "verified": true,
        "timestamp": 0.0,
        "flagged": false
      },
      "mandatory_disclosures": {
        "read": true,
        "matched_disclosures": ["call_recording_notice"],
        "missing_disclosures": []
      },
      "purpose_declaration": {
        "disclosed": true,
        "interaction_number": 1,
        "flagged": false
      },
      "prohibited_phrases": {
        "used": false,
        "instances": []
      },
      "sensitive_data": {
        "shared": false,
        "instances": []
      }
    },
    "quality": {
      "sentiment_analysis": {
        "trajectory": [
          {"timestamp": 0.0, "level": 4},
          {"timestamp": 30.0, "level": 5}
        ],
        "first_30s_avg": 4,
        "last_30s_avg": 5,
        "drop_magnitude": 0,
        "flagged_drop": false,
        "negative_periods": []
      },
      "greeting": {
        "present": true,
        "timestamp": 0.0,
        "flagged_missing": false,
        "flagged_late": false
      },
      "empathetic_language": {
        "used": true,
        "instances": [6.0, 12.3],
        "three_min_intervals_checked": 1,
        "intervals_without_empathy": 0,
        "flagged": false
      }
    },
    "coaching": {
      "recommendations": [
        {
          "category": "greeting",
          "priority": "low",
          "description": "Agent provided an excellent greeting and immediately offered assistance"
        }
      ],
      "customer_effort_score": 1
    }
  },
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": "2024-01-15T14:32:15.123000",
    "processing_time_ms": 45230,
    "error_message": null
  }
}

Key Points

status: "completed" - Analysis finished successfully
results object is fully populated with all metrics
customer_effort_score: 1 indicates excellent customer experience (1-5 scale, lower is better)
All compliance checks passed (flagged: false)

Processing Analysis

An analysis that is currently being processed:

_example-processing.json
{
  "id": "660f9511-f3ac-52e5-b827-557766551111",
  "object": "analysis",
  "created": 1705334100,
  "status": "processing",
  "livemode": false,
  "call": {
    "agent_id": "agent_002",
    "contact_id": "customer_67890",
    "duration_ms": 98200,
    "duration_seconds": 98.2
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/660f9511-f3ac-52e5-b827-557766551111.wav",
    "size_bytes": 823456,
    "format": "mp3",
    "duration_seconds": 98.2
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": null,
    "processing_time_ms": null,
    "error_message": null
  }
}

Key Points

status: "processing" - Analysis in progress
transcript and results are null until processing completes
Use webhooks to get notified when complete
Or poll this endpoint periodically

Failed Analysis

An analysis that encountered an error during processing:

_example-failed.json
{
  "id": "770fa622-f4bd-63f6-c938-668877662222",
  "object": "analysis",
  "created": 1705334050,
  "status": "failed",
  "livemode": false,
  "call": {
    "agent_id": "agent_003",
    "contact_id": "customer_99999",
    "duration_ms": null,
    "duration_seconds": null
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/770fa622-f4bd-63f6-c938-668877662222.wav",
    "size_bytes": 1234,
    "format": "wav",
    "duration_seconds": null
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "webhook_url": null,
    "completed_at": "2024-01-15T14:30:25.456000",
    "processing_time_ms": 2500,
    "error_message": "Transcription failed: audio file corrupted or unreadable"
  }
}

Error Handling

status: "failed" - Analysis encountered an error
Check metadata.error_message for details
Common errors: corrupted audio, unsupported format, file too short
Contact support if errors persist

Compliance Violations

An analysis showing multiple compliance and quality issues:

_example-compliance-violation.json
{
  "id": "880fb733-f5ce-7407-d049-779988773333",
  "object": "analysis",
  "created": 1705334200,
  "status": "completed",
  "livemode": false,
  "call": {
    "agent_id": "agent_004",
    "contact_id": "customer_11111",
    "duration_ms": 180000,
    "duration_seconds": 180.0
  },
  "results": {
    "compliance": {
      "identity_verification": {
        "verified": false,
        "timestamp": null,
        "flagged": true
      },
      "mandatory_disclosures": {
        "read": false,
        "matched_disclosures": [],
        "missing_disclosures": ["call_recording_notice", "privacy_policy"]
      },
      "prohibited_phrases": {
        "used": true,
        "instances": [
          {"phrase": "guaranteed returns", "timestamp": 45.2},
          {"phrase": "risk-free investment", "timestamp": 78.5}
        ]
      },
      "sensitive_data": {
        "shared": true,
        "instances": [
          {"type": "SSN", "timestamp": 92.1},
          {"type": "credit_card", "timestamp": 105.3}
        ]
      }
    },
    "quality": {
      "interruptions": {
        "count": 12,
        "instances": [15.2, 23.4, 34.5, 45.6, 56.7, 67.8, 78.9, 89.0, 99.1, 109.2, 119.3, 129.4],
        "flagged": true
      },
      "empathetic_language": {
        "used": false,
        "instances": [],
        "three_min_intervals_checked": 3,
        "intervals_without_empathy": 3,
        "flagged": true
      }
    },
    "coaching": {
      "recommendations": [
        {
          "category": "compliance",
          "priority": "high",
          "description": "CRITICAL: Agent did not verify identity or read required disclosures. This is a legal compliance issue."
        },
        {
          "category": "compliance",
          "priority": "high",
          "description": "CRITICAL: Agent used prohibited phrases ('guaranteed returns', 'risk-free') which violate SEC regulations."
        }
      ],
      "customer_effort_score": 5
    }
  }
}

Critical Issues Flagged

This example shows severe compliance violations:

❌ Identity not verified (flagged: true)
❌ Missing mandatory disclosures
❌ Prohibited phrases used (regulatory violation)
❌ Sensitive data shared verbally
❌ Excessive interruptions (12 instances)
❌ No empathetic language used
customer_effort_score: 5 (worst possible score)

Using These Examples

In Your Tests

import requests
import json

# Load the example for comparison
with open('_example-completed.json') as f:
    expected_structure = json.load(f)

# Make API call
response = requests.post('https://api.callcov.com/api/v1/analysis', ...)

# Verify structure matches
assert response.json().keys() == expected_structure.keys()

Schema Validation

from app.schemas.analysis import AnalysisResponse

# Validate response matches schema
analysis = AnalysisResponse(**response.json())

Regenerating Examples

These examples are automatically generated from Pydantic schemas:

# Regenerate all examples
make gen-api-examples

# Verify examples are valid
python scripts/generate-api-examples.py --validate-only

Field Reference - Complete field documentation
Create Analysis - Submit audio for analysis
Retrieve Analysis - Get analysis results
Webhooks Guide - Get notified when complete

Example Scenarios​

Completed Analysis​

Processing Analysis​

Failed Analysis​

Compliance Violations​

Using These Examples​

In Your Tests​

Schema Validation​

Regenerating Examples​

Related​