Skip to main content
POST
/
api
/
v1
/
voice
/
upload
Upload Voice File
curl --request POST \
  --url https://api.example.com/api/v1/voice/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "parties": "<string>",
  "contract_type": "<string>"
}
'
{
  "transcript": "<string>",
  "terms": {},
  "processing_status": "<string>",
  "confidence_score": 123
}

Overview

This endpoint accepts audio file uploads and immediately processes them to extract contract terms. Unlike the process endpoint which requires a URL, this endpoint handles direct file uploads.

Request Parameters

file
file
required
Audio file containing the voice recordingSupported formats:
  • .wav - WAV audio
  • .mp3 - MP3 audio
  • .m4a - M4A/AAC audio
  • .ogg - OGG Vorbis audio
Recommended specifications:
  • Sample rate: 16 kHz or higher
  • Bit rate: 128 kbps minimum
  • Channels: Mono or stereo
  • Max file size: 100 MB
parties
string
Optional JSON string containing party informationFormat: '[{"phone":"+254712345678","role":"buyer"}]'
contract_type
string
default:"agricultural_supply"
Type of contract being processedOptions: agricultural_supply, service_agreement, loan_agreement

Response

transcript
string
Full text transcript of the uploaded audio
terms
object
Extracted contract terms including:
  • total_amount: Transaction amount
  • currency: Currency code
  • delivery_date: Delivery deadline
  • delivery_location: Delivery address
  • quality_requirements: Product specifications
  • payment_terms: Payment conditions
processing_status
string
Processing outcome: completed, failed, or partial
confidence_score
float
Extraction confidence level (0.0 to 1.0)

Example Request

Using cURL

curl -X POST https://api.voicepact.com/api/v1/voice/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/contract_recording.mp3" \
  -F "contract_type=agricultural_supply" \
  -F 'parties=[{"phone":"+254712345678","role":"buyer"},{"phone":"+254787654321","role":"seller"}]'

Using Python

import requests

url = "https://api.voicepact.com/api/v1/voice/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

files = {
    "file": open("contract_recording.mp3", "rb")
}
data = {
    "contract_type": "agricultural_supply",
    "parties": '[{"phone":"+254712345678","role":"buyer"}]'
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Using JavaScript

const formData = new FormData();
formData.append('file', audioFile); // File object from input
formData.append('contract_type', 'agricultural_supply');
formData.append('parties', JSON.stringify([
  {phone: '+254712345678', role: 'buyer'}
]));

fetch('https://api.voicepact.com/api/v1/voice/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Example Response

{
  "transcript": "I agree to sell 50 kilograms of coffee beans at 800 shillings per kilogram. The buyer agrees to pay 40,000 shillings total. Delivery will be to Thika warehouse by March 15th. The coffee must be grade AA with moisture content below 11%.",
  "terms": {
    "total_amount": 40000,
    "currency": "KES",
    "quantity": "50 kg",
    "unit_price": 800,
    "product": "coffee beans",
    "delivery_date": "2026-03-15",
    "delivery_location": "Thika warehouse",
    "quality_requirements": [
      "Grade AA coffee",
      "Moisture content below 11%"
    ],
    "payment_terms": "Full payment of KES 40,000"
  },
  "processing_status": "completed",
  "confidence_score": 0.91
}

Error Responses

400 Bad Request - Unsupported Format
Audio file format not supported
{
  "detail": "Unsupported audio format"
}
400 Bad Request - Processing Failed
Audio could not be transcribed or analyzed
{
  "detail": "File processing failed: Audio quality too low for transcription"
}
413 Payload Too Large
File exceeds maximum size limit
{
  "detail": "File size exceeds 100 MB limit"
}
500 Internal Server Error
Unexpected server error during processing
{
  "detail": "File processing failed: Internal transcription service error"
}

Processing Steps

  1. File Upload: Audio file received and validated
  2. Temporary Storage: File saved to temporary location
  3. Format Validation: File type and quality checked
  4. Transcription: Audio converted to text using Whisper AI
  5. Term Extraction: AI analyzes transcript for contract terms
  6. Cleanup: Temporary files removed
  7. Response: Results returned immediately

Best Practices

Audio Quality

  • Use lossless formats (WAV) for best results
  • Minimize background noise
  • Ensure clear speech from all parties
  • Test with a small sample first

File Size

  • Compress long recordings using efficient codecs
  • Trim silence from beginning and end
  • Consider splitting very long calls

Error Handling

  • Check processing_status before using terms
  • Validate confidence_score is acceptable (> 0.7 recommended)
  • Implement retry logic for network failures
  • Save the transcript for manual review if needed

Use Cases

Mobile App Integration: Users record agreements on their phones and upload directly Web Portal: Contract parties upload pre-recorded negotiations Testing: Developers test contract extraction with sample audio Archive Processing: Batch process historical recordings

Build docs developers (and LLMs) love