Contracts API

Contracts API Reference

Create and manage multi-party smart contracts with automatic execution, escrow functionality, and milestone-based payments. Perfect for service agreements, freelance contracts, and business deals.

Overview

The Contracts API enables you to create sophisticated multi-party agreements with built-in payment processing, milestone tracking, and automated execution. Each contract can have multiple parties with different roles and payment responsibilities.

Multi-Party

Support for unlimited parties with customizable roles and permissions

Milestones

Break contracts into milestones with conditional payments

Automation

Automatic execution based on conditions and approvals

POSTCreate Contract

Create a new multi-party contract with terms and conditions

Endpoint

POST /contracts

Request Body

{
  "title": "Website Development Contract",
  "description": "Complete website development with 3 milestones",
  "total_amount": 5000.00,
  "currency": "USD",
  "parties": [
    {
      "user_id": "usr_client123",
      "role": "client",
      "name": "Acme Corp",
      "responsibilities": ["Provide requirements", "Review deliverables"]
    },
    {
      "user_id": "usr_dev456", 
      "role": "contractor",
      "name": "John Developer",
      "responsibilities": ["Deliver website", "Provide support"]
    }
  ],
  "milestones": [
    {
      "title": "Design Approval",
      "description": "Complete website design and wireframes",
      "amount": 1500.00,
      "due_date": "2024-02-15T00:00:00Z",
      "requirements": ["Design mockups", "Client approval"]
    },
    {
      "title": "Development Complete", 
      "description": "Fully functional website",
      "amount": 2500.00,
      "due_date": "2024-03-15T00:00:00Z",
      "requirements": ["Working website", "All features implemented"]
    },
    {
      "title": "Launch & Support",
      "description": "Website launch and 30 days support",
      "amount": 1000.00,
      "due_date": "2024-04-15T00:00:00Z", 
      "requirements": ["Live website", "Documentation"]
    }
  ],
  "terms": {
    "auto_execute": true,
    "dispute_resolution": "arbitration",
    "late_penalty": 0.05
  }
}

Response (201 Created)

{
  "success": true,
  "data": {
    "contract_id": "ctr_1a2b3c4d5e6f",
    "title": "Website Development Contract",
    "status": "pending_signatures",
    "total_amount": 5000.00,
    "currency": "USD",
    "escrow_id": "esc_1a2b3c4d5e6f",
    "parties": [
      {
        "user_id": "usr_client123",
        "role": "client", 
        "signature_status": "pending",
        "signed_at": null
      },
      {
        "user_id": "usr_dev456",
        "role": "contractor",
        "signature_status": "pending", 
        "signed_at": null
      }
    ],
    "milestones": [
      {
        "milestone_id": "mls_1a2b3c4d",
        "title": "Design Approval",
        "status": "pending",
        "amount": 1500.00,
        "due_date": "2024-02-15T00:00:00Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_1a2b3c4d5e6f",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GETGet Contract

Retrieve contract details and current status

Endpoint

GET /contracts/{contract_id}

Response (200 OK)

{
  "success": true,
  "data": {
    "contract_id": "ctr_1a2b3c4d5e6f",
    "title": "Website Development Contract", 
    "status": "active",
    "total_amount": 5000.00,
    "paid_amount": 1500.00,
    "remaining_amount": 3500.00,
    "currency": "USD",
    "progress": 0.33,
    "parties": [
      {
        "user_id": "usr_client123",
        "role": "client",
        "signature_status": "signed",
        "signed_at": "2024-01-16T09:15:00Z"
      },
      {
        "user_id": "usr_dev456", 
        "role": "contractor",
        "signature_status": "signed",
        "signed_at": "2024-01-16T10:22:00Z"
      }
    ],
    "current_milestone": {
      "milestone_id": "mls_2b3c4d5e",
      "title": "Development Complete",
      "status": "in_progress",
      "amount": 2500.00,
      "due_date": "2024-03-15T00:00:00Z",
      "progress": 0.45
    },
    "milestones_completed": 1,
    "total_milestones": 3,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-02-20T14:22:00Z"
  }
}

PUTUpdate Milestone

Update milestone status and trigger payments

Endpoint

PUT /contracts/{contract_id}/milestones/{milestone_id}

Request Body

{
  "status": "completed",
  "completion_notes": "Design has been approved by client",
  "deliverables": [
    {
      "name": "Design Mockups",
      "url": "https://files.example.com/mockups.pdf"
    },
    {
      "name": "Wireframes", 
      "url": "https://files.example.com/wireframes.pdf"
    }
  ],
  "completion_evidence": {
    "client_approval_email": "approval_email.pdf",
    "signed_deliverable": "signed_mockup.pdf"
  }
}

GETList Contracts

Retrieve a list of contracts with filtering options

Endpoint

GET /contracts

Query Parameters

Parameter	Type	Description
status	string	Filter by status: pending_signatures, active, completed, cancelled
user_id	string	Filter by user involved in contract
limit	integer	Number of results to return (max 100, default 20)
offset	integer	Number of results to skip (for pagination)

Contract Statuses

Understanding the contract lifecycle

pending_signatures

Waiting for all parties to sign the contract

active

Contract is active and milestones are being executed

completed

All milestones completed and payments processed

cancelled

Contract was cancelled, funds returned to appropriate parties

Common Errors

400 Bad Request - Invalid Party

{
  "success": false,
  "error": {
    "code": "INVALID_PARTY",
    "message": "User usr_invalid123 is not a valid Waffy user",
    "details": {
      "user_id": "usr_invalid123"
    }
  }
}

409 Conflict - Milestone Already Completed

{
  "success": false,
  "error": {
    "code": "MILESTONE_ALREADY_COMPLETED",
    "message": "Milestone mls_1a2b3c4d has already been completed",
    "details": {
      "milestone_id": "mls_1a2b3c4d",
      "completed_at": "2024-01-20T15:30:00Z"
    }
  }
}

Contract Templates

Use pre-built templates for common contract types

View Templates

Webhooks Integration

Get real-time notifications for contract events

Setup Webhooks