Skip to main content
POST
/
api
/
v1
/
sms
/
send
/
contract
Send Contract SMS
curl --request POST \
  --url https://api.example.com/api/v1/sms/send/contract \
  --header 'Content-Type: application/json' \
  --data '
{
  "contract_id": "<string>",
  "recipients": [
    {}
  ],
  "terms": {}
}
'
{
  "contract_id": "<string>",
  "recipients": [
    {}
  ],
  "message": "<string>",
  "sms_result": {}
}

​
Overview

Send a specially formatted SMS message containing contract details to all parties involved. The message includes contract ID, terms summary, and confirmation instructions.

​
Request Body

​
contract_id
string
default:"AG-DEMO-001"
Contract identifier
​
recipients
array
required
Array of phone numbers for contract parties
​
terms
object
Contract terms object used to generate the message

​
Response

​
contract_id
string
The contract identifier
​
recipients
array
Phone numbers that received the message
​
message
string
The generated contract message text
​
sms_result
object
Result object from the SMS service

​
Example Request

curl -X POST http://localhost:8000/api/v1/sms/send/contract \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "AG-2024-001",
    "recipients": ["+254712345678", "+254798765432"],
    "terms": {
      "product": "Maize",
      "quantity": "100 bags",
      "total_amount": 50000,
      "currency": "KES",
      "delivery_deadline": "2024-02-15"
    }
  }'

​
Example Response

{
  "contract_id": "AG-2024-001",
  "recipients": [
    "+254712345678",
    "+254798765432"
  ],
  "message": "VoicePact Contract AG-2024-001\nProduct: Maize (100 bags)\nAmount: KES 50,000\nDelivery: 2024-02-15\nReply YES-AG-2024-001 to confirm",
  "sms_result": {
    "status": "success",
    "message_ids": ["ATXid_abc123", "ATXid_def456"],
    "sent_count": 2
  }
}

​
Message Format

The generated message follows this template: 
VoicePact Contract {contract_id}
Product: {product} ({quantity})
Amount: {currency} {total_amount:,}
Delivery: {delivery_deadline}
Reply YES-{contract_id} to confirm

​
Error Response

{
  "detail": "Contract SMS failed: Invalid contract data"
}

​
Status Codes

  • 200 - Contract SMS sent successfully
  • 500 - SMS send failed
  • 503 - SMS service unavailable

​
Use Cases

  • Notify parties when contract is created
  • Send contract confirmation requests
  • Distribute contract terms summary
  • Provide SMS-based confirmation instructions

​
Implementation

This endpoint uses the generate_contract_sms() method from the Africa’s Talking client (source: africastalking_client.py:224-242) to format contract details into a concise SMS message.

Create Contract

Create a new contract

SMS Webhook

Handle confirmation responses

Bulk SMS

Send bulk messages

Contract Status

Check contract confirmation status

Build docs developers (and LLMs) love

Get started for freeTalk to us