Skip to main content
POST
/
api
/
v1
/
contracts
/
create
/
manual
Create Manual Contract
curl --request POST \
  --url https://api.example.com/api/v1/contracts/create/manual \
  --header 'Content-Type: application/json' \
  --data '
{
  "product": "<string>",
  "quantity": "<string>",
  "unit": "<string>",
  "unit_price": 123,
  "total_amount": 123,
  "currency": "<string>",
  "delivery_location": "<string>",
  "delivery_deadline": "<string>",
  "quality_requirements": "<string>",
  "parties": [
    {}
  ],
  "contract_type": "<string>"
}
'
{
  "contract_id": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "expires_at": "<string>",
  "total_amount": 123,
  "currency": "<string>",
  "parties": [
    {}
  ],
  "contract_hash": "<string>"
}

​
Overview

Create a contract by providing structured terms directly, bypassing the voice processing pipeline. This is useful for contracts created through forms, existing agreements, or when voice input is not available.

​
Request Body

​
product
string
required
Product or service name
​
quantity
string
Quantity or amount (e.g., “100 bags”, “5 units”)
​
unit
string
Unit of measurement (e.g., “kg”, “bags”, “hours”)
​
unit_price
number
Price per unit
​
total_amount
number
required
Total contract amount
​
currency
string
default:"KES"
Currency code (e.g., “KES”, “USD”)
​
delivery_location
string
Delivery or service location
​
delivery_deadline
string
Delivery deadline (ISO 8601 date string)
​
quality_requirements
string
Quality specifications or requirements
​
parties
array
required
Array of contract parties (minimum 2)
​
contract_type
string
default:"agricultural_supply"
Type of contract (e.g., “agricultural_supply”, “service”, “rental”)

​
Response

​
contract_id
string
Unique contract identifier
​
status
string
Contract status (initially “pending”)
​
created_at
string
ISO 8601 timestamp of creation
​
expires_at
string
Contract expiration timestamp (if applicable)
​
total_amount
number
Total contract value
​
currency
string
Currency code
​
parties
array
Array of contract parties with their details
​
contract_hash
string
Cryptographic hash of the contract for integrity verification

​
Example Request

curl -X POST http://localhost:8000/api/v1/contracts/create/manual \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Maize",
    "quantity": "100",
    "unit": "bags",
    "unit_price": 500,
    "total_amount": 50000,
    "currency": "KES",
    "delivery_location": "Nairobi Central Market",
    "delivery_deadline": "2024-02-15",
    "quality_requirements": "Grade A, moisture content <13%",
    "parties": [
      {
        "phone": "+254712345678",
        "role": "seller",
        "name": "John Farmer"
      },
      {
        "phone": "+254798765432",
        "role": "buyer",
        "name": "ABC Traders Ltd"
      }
    ],
    "contract_type": "agricultural_supply"
  }'

​
Example Response

{
  "contract_id": "AG-2024-001",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00.000Z",
  "expires_at": null,
  "total_amount": 50000.0,
  "currency": "KES",
  "parties": [
    {
      "phone_number": "+254712345678",
      "role": "seller",
      "name": "John Farmer"
    },
    {
      "phone_number": "+254798765432",
      "role": "buyer",
      "name": "ABC Traders Ltd"
    }
  ],
  "contract_hash": "blake2b:a1b2c3d4e5f6..."
}

​
Status Codes

  • 201 - Contract created successfully
  • 400 - Invalid request (missing required fields)
  • 422 - Validation error (e.g., invalid phone numbers)
  • 500 - Server error during contract creation

​
Workflow

1

Submit Contract Data

Send POST request with all contract details
2

Contract Generated

System creates contract with unique ID and hash
3

SMS Notifications Sent

All parties receive SMS with contract summary and confirmation instructions
4

Parties Confirm

Parties reply via SMS or USSD to sign the contract
5

Contract Confirmed

Once all parties sign, contract status changes to “confirmed”

​
Generated Transcript

The endpoint automatically generates a human-readable transcript from the structured data: 
Manual contract creation: Maize - 100 bags for KES 50,000
This transcript is stored for record-keeping and audit purposes.

​
Background Tasks

After contract creation, the following tasks are triggered automatically:
  1. SMS Notifications: All parties receive contract details via SMS
  2. Signature Records: Pending signature records created for each party
  3. Audit Log: Contract creation event logged

​
Use Cases

Web Form Submissions

Create contracts from web dashboard forms

Bulk Import

Import existing agreements into VoicePact

API Integration

Programmatically create contracts from other systems

Offline Contracts

Create contracts when voice recording isn’t available

​
Validation Rules

  • Minimum 2 parties required
  • Phone numbers must include country code (e.g., +254…)
  • Total amount must be positive
  • Parties must have unique phone numbers
  • At least one buyer and one seller recommended

​
Implementation

This endpoint wraps the standard contract creation logic (POST /api/v1/contracts/create) by converting manual input into the internal contract format. Source: contracts.py:134-183

Create from Voice

Create contract from voice transcript

Get Contract

Retrieve contract details

Confirm Contract

Sign/confirm a contract

Contract Status

Check confirmation progress

Build docs developers (and LLMs) love

Get started for freeTalk to us