Skip to main content

​
Welcome to VoicePact API

The VoicePact API is a RESTful service that enables voice-based contract creation and management for underserved communities. Built with FastAPI, it provides a modern, high-performance interface for creating, managing, and executing binding agreements through voice calls, SMS, and mobile money integration.

​
Base URL

The API is versioned and accessible at: 
http://your-domain.com/api/v1
All endpoints are prefixed with /api/v1 as configured in the application settings.

​
API Version

Current Version: 1.0.0 The API uses URL path versioning. Version 1 endpoints are available at /api/v1/*.

​
Core Features

Voice Processing

Convert voice recordings into structured contracts with automatic term extraction

Contract Management

Create, manage, and track binding agreements with cryptographic signatures

Mobile Money Integration

Process payments and escrow through Africa’s Talking payment gateway

SMS Notifications

Send contract confirmations and updates via SMS

​
Available Endpoints

​
Voice Processing

  • POST /api/v1/voice/conference/create - Create voice conference for contract negotiation
  • POST /api/v1/voice/process - Process voice recording into contract
  • POST /api/v1/voice/upload - Upload audio file for processing
  • POST /api/v1/voice/webhook - Webhook for voice call events

​
Contract Management

  • POST /api/v1/contracts/create - Create contract from transcript
  • POST /api/v1/contracts/create/manual - Create contract manually
  • GET /api/v1/contracts/{contract_id} - Get contract by ID
  • GET /api/v1/contracts/ - List contracts with filtering
  • PUT /api/v1/contracts/{contract_id} - Update contract
  • POST /api/v1/contracts/{contract_id}/confirm - Confirm contract by phone
  • GET /api/v1/contracts/{contract_id}/status - Get contract status

​
Payments

  • POST /api/v1/payments/checkout - Initiate mobile money checkout
  • POST /api/v1/payments/webhook - Payment webhook handler
  • GET /api/v1/payments/{payment_id} - Get payment details
  • GET /api/v1/payments/contract/{contract_id} - Get payments for contract
  • GET /api/v1/payments/wallet/balance - Get wallet balance

​
SMS Integration

  • POST /api/v1/sms/send - Send single SMS
  • POST /api/v1/sms/send/bulk - Send bulk SMS
  • POST /api/v1/sms/send/contract - Send contract confirmation SMS
  • POST /api/v1/sms/webhook - SMS webhook handler
  • GET /api/v1/sms/status - Check SMS service status

​
USSD

  • POST /api/v1/ussd - USSD menu handler

​
WebSocket

  • WS /api/v1/ws - Real-time contract updates

​
Quick Start

​
1. Check API Health

curl http://your-domain.com/health
Response: 
{
  "status": "healthy",
  "services": {
    "database": "connected",
    "redis": "connected"
  },
  "timestamp": 1234567890.123
}

​
2. Create a Simple Contract

curl -X POST http://your-domain.com/api/v1/contracts/create/manual \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Maize",
    "quantity": "100",
    "unit": "bags",
    "total_amount": 50000,
    "currency": "KES",
    "parties": [
      {"phone": "+254712345678", "role": "seller", "name": "John Doe"},
      {"phone": "+254723456789", "role": "buyer", "name": "Jane Smith"}
    ]
  }'

​
3. Check Contract Status

curl http://your-domain.com/api/v1/contracts/AG-2024-001/status

​
Response Format

All API responses follow a consistent JSON format:

​
Success Response

{
  "contract_id": "AG-2024-001",
  "status": "pending",
  "created_at": "2024-03-15T10:30:00",
  "parties": [...]
}

​
Error Response

{
  "detail": "Contract not found"
}

​
Rate Limiting

Currently, there are no enforced rate limits. However, we recommend:
  • Maximum 100 requests per minute per IP
  • Maximum 1000 requests per hour per IP

​
CORS Support

The API supports CORS for the following origins:
  • http://localhost:3000
  • http://127.0.0.1:3000
Custom origins can be configured via the CORS_ORIGINS environment variable.

​
Compression

The API supports GZip compression for responses larger than 1000 bytes. Include the Accept-Encoding: gzip header in your requests.

​
Environments

  • Debug mode enabled
  • Detailed error messages
  • Interactive API docs at /docs
  • Base URL: http://localhost:8000/api/v1

​
Interactive Documentation

In development mode, interactive API documentation is available at:
  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
Note: These endpoints are disabled in production for security.

​
Next Steps

Authentication

Learn about API security and authentication methods

Error Handling

Understand error codes and how to handle them

Build docs developers (and LLMs) love

Get started for freeTalk to us