Skip to main content
POST
/
api
/
v1
/
voice
/
process
Process Voice Recording
curl --request POST \
  --url https://api.example.com/api/v1/voice/process \
  --header 'Content-Type: application/json' \
  --data '
{
  "audio_url": "<string>",
  "parties": [
    {}
  ],
  "contract_type": "<string>"
}
'
{
  "contract_id": "<string>",
  "transcript": "<string>",
  "terms": {},
  "contract_hash": "<string>",
  "contract_summary": "<string>",
  "processing_status": "<string>",
  "confidence_score": 123,
  "created_at": "<string>"
}

​
Overview

This endpoint analyzes voice recordings to extract contract terms, generate transcripts, and create enforceable digital contracts. It uses AI to understand verbal agreements and structure them into formal contracts.

​
Request Body

​
audio_url
string
required
URL pointing to the audio recording fileSupported formats: .wav, .mp3, .m4a, .oggExample: "https://storage.example.com/recordings/contract_call.mp3"
​
parties
array
required
List of contract party objects (minimum 2 required)Each party object must contain:
  • phone: Phone number (string)
  • role: Party role - "buyer" or "seller" (string)
  • name: Full name (string, optional)
Example:
[
  {"phone": "+254712345678", "role": "buyer", "name": "John Kamau"},
  {"phone": "+254787654321", "role": "seller", "name": "Mary Wanjiku"}
]
​
contract_type
string
default:"agricultural_supply"
Type of contract being processedOptions: agricultural_supply, service_agreement, loan_agreement

​
Response

​
contract_id
string
Unique identifier for the generated contract
​
transcript
string
Full text transcript of the voice recording
​
terms
object
Extracted contract terms including:
  • total_amount: Numeric value
  • currency: Currency code (e.g., “KES”)
  • delivery_date: ISO date string
  • delivery_location: Location description
  • quality_requirements: List of quality criteria
  • payment_terms: Payment conditions
​
contract_hash
string
Cryptographic hash of the contract for verification
​
contract_summary
string
Human-readable summary of the contract terms
​
processing_status
string
Processing result: completed, failed, or partial
​
confidence_score
float
AI confidence score (0.0 to 1.0) for term extraction accuracy
​
created_at
string
ISO 8601 timestamp of contract creation

​
Example Request

curl -X POST https://api.voicepact.com/api/v1/voice/process \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "audio_url": "https://storage.voicepact.com/recordings/call_12345.mp3",
    "parties": [
      {
        "phone": "+254712345678",
        "role": "buyer",
        "name": "John Kamau"
      },
      {
        "phone": "+254787654321",
        "role": "seller",
        "name": "Mary Wanjiku"
      }
    ],
    "contract_type": "agricultural_supply"
  }'

​
Example Response

{
  "contract_id": "contract_9f8e7d6c5b4a",
  "transcript": "Buyer: I would like to purchase 100 bags of maize at 3500 shillings per bag. Seller: I agree to sell 100 bags at 3500 shillings each, delivery by next Friday to Nairobi depot. Quality must be grade A, moisture content below 13.5%...",
  "terms": {
    "total_amount": 350000,
    "currency": "KES",
    "quantity": "100 bags",
    "unit_price": 3500,
    "product": "maize",
    "delivery_date": "2026-03-13",
    "delivery_location": "Nairobi depot",
    "quality_requirements": [
      "Grade A maize",
      "Moisture content below 13.5%"
    ],
    "payment_terms": "Payment upon delivery"
  },
  "contract_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "contract_summary": "Agreement for sale of 100 bags of maize at KES 3,500 per bag (total KES 350,000). Delivery by March 13, 2026 to Nairobi depot. Quality: Grade A, moisture below 13.5%.",
  "processing_status": "completed",
  "confidence_score": 0.94,
  "created_at": "2026-03-06T14:23:45.123456Z"
}

​
Error Responses

​
400 Bad Request
Missing or invalid parameters
{
  "detail": "Audio URL is required"
}
​
400 Voice Processing Failed
Audio could not be processed or terms could not be extracted
{
  "detail": "Voice processing failed: Unable to transcribe audio - poor quality"
}
​
500 Internal Server Error
Unexpected processing error
{
  "detail": "Voice processing failed: Database connection timeout"
}

​
Processing Pipeline

  1. Audio Download: Fetch recording from provided URL
  2. Transcription: Convert speech to text using Whisper AI
  3. Term Extraction: Parse transcript to identify contract terms
  4. Contract Generation: Structure terms into formal contract
  5. Hash Creation: Generate cryptographic hash for verification
  6. Database Storage: Save contract and party information
  7. SMS Notifications: Send confirmation requests to all parties

​
Best Practices

  • Ensure audio quality is clear (minimal background noise)
  • Include all party information in the request
  • Verify confidence_score is above 0.7 for reliable extraction
  • Store the contract_hash for future verification
  • Monitor the webhook endpoint for status updates

Build docs developers (and LLMs) love

Get started for freeTalk to us