POST
/
api
/
v1
/
analyses
Create Analysis
curl --request POST \
  --url https://api.example.com/api/v1/analyses \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_id": "<string>",
  "file_name": "<string>",
  "file_url": "<string>",
  "metadata": {
    "caller_id": "<string>",
    "agent_id": "<string>",
    "call_duration": 123,
    "call_type": "<string>"
  },
  "priority": "<string>",
  "transcription_engine": "<string>"
}
'
{
  "id": "<string>",
  "organization_id": "<string>",
  "file_id": "<string>",
  "file_name": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "created_at": "<string>",
  "result": {
    "fraud_score": 123,
    "fraud_indicators": [
      {}
    ],
    "risk_level": "<string>",
    "transcription": [
      {}
    ],
    "analysis": {}
  }
}

​
Request

​
file_id
string
The ID of the uploaded audio file (from upload endpoint)
​
file_name
string
required
The original filename of the audio file
​
file_url
string
Optional direct URL to the audio file (alternative to file_id)
​
metadata
object
Additional metadata for the analysis
​
priority
string
default:"medium"
Priority level for processing (high, medium, low)
​
transcription_engine
string
default:"whisper"
Transcription engine to use (whisper, parakeet, nemo)

​
Response

​
id
string
Unique identifier for the analysis
​
organization_id
string
Organization that owns this analysis
​
file_id
string
ID of the associated audio file
​
file_name
string
Name of the audio file
​
status
string
Current status of the analysisPossible values:
  • pending - Analysis queued for processing
  • processing - Currently being analyzed
  • completed - Analysis finished successfully
  • error - Analysis failed
  • needs_review - Flagged for manual review
​
priority
string
Processing priority level
​
created_at
string
ISO 8601 timestamp of creation
​
result
object
Analysis results (available when status is completed)

​
Example Request

curl -X POST https://api.authentivoice.com/api/v1/analyses \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "x-orgid: org_123456" \
  -d '{
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "customer_call_20240110.mp3",
    "priority": "high",
    "metadata": {
      "caller_id": "+1234567890",
      "agent_id": "agent_001",
      "call_type": "inbound"
    }
  }'

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "org_123456",
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_name": "customer_call_20240110.mp3",
  "status": "pending",
  "priority": "high",
  "metadata": {
    "caller_id": "+1234567890",
    "agent_id": "agent_001",
    "call_type": "inbound"
  },
  "created_at": "2024-01-10T15:30:00Z",
  "updated_at": "2024-01-10T15:30:00Z"
}

​
Processing Workflow

1

Create Analysis

Submit the analysis request with file information
2

Audio Processing

System downloads and processes the audio file
  • Trim silence
  • Normalize volume
  • Convert format if needed
3

Transcription

Generate text transcript using specified engine
  • Whisper (default): Local processing
  • Parakeet: Cloud-based, fast
  • NeMo: High accuracy
4

AI Analysis

Analyze transcript for fraud indicators
  • Pattern detection
  • Compliance checking
  • Risk scoring
5

Results Available

Analysis complete, results available via GET endpoint

​
Webhook Notification

If webhooks are configured, you’ll receive a notification when analysis completes: 
{
  "event": "analysis.completed",
  "timestamp": "2024-01-10T15:35:00Z",
  "data": {
    "analysis_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "fraud_score": 0.85,
    "risk_level": "high"
  }
}

​
Error Responses

{
  "error": {
    "status": 400,
    "message": "Invalid request",
    "details": {
      "file_name": "Required field missing"
    }
  }
}

{
  "error": {
    "status": 404,
    "message": "File not found",
    "details": {
      "file_id": "No file found with ID: 550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

{
  "error": {
    "status": 429,
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 60,
      "limit": 100,
      "remaining": 0
    }
  }
}