API & MCP reference

All API requests require an API key in the Authorization header. Keys start with ddm_live_ and are scoped to the workspace they were created in. Each key is shown once at creation — store it somewhere safe.

curl https://ddmflow.com/api/clients \
  -H "Authorization: Bearer ddm_live_xxxxxxxxxxxxxxxxxxxx"

Generate one at Settings → API keys — included on Pro and Ultra, or Basic with the MCP add-on.

https://ddmflow.com/api

All API endpoints sit beneath this base. JSON request + response.

DDM Flow ships a built-in MCP server so your AI agent can call tools directly — no glue code required. Same auth, same tier gating.

claude mcp add --transport http ddm-flow https://ddmflow.com/mcp \
  --header "Authorization: Bearer ddm_live_xxxxx"

The model handles tool calls automatically. Every tool the server registers is listed here — this page is generated from the registry, so it cannot fall behind it.

A key carries only the scopes you give it, and a connected app only the ones approved on the consent screen. A browser session is never scope-limited — a person at the keyboard has their role instead.

• invoices:readSee your invoices and payments
• invoices:writeCreate, send and update invoices and record payments
• quotes:readSee your quotes
• quotes:writeCreate, send and update quotes
• clients:readSee your clients
• clients:writeAdd and update clients
• items:readSee your products and services
• items:writeAdd and update products and services
• credit_notes:readSee your credit notes
• credit_notes:writeCreate, issue, allocate and void credit notes
• expenses:readSee your expenses and receipts
• expenses:writeRecord, change and delete expenses
• suppliers:readSee your suppliers
• suppliers:writeAdd and update suppliers
• bills:readSee your supplier bills
• bills:writeRecord and pay supplier bills
• bank:readSee your bank transactions
• bank:writeImport bank statements and match transactions
• journals:readSee your general ledger, cash book and fixed assets
• journals:writePost journals, cash book entries and fixed assets
• tax:readSee your VAT returns
• tax:writePrepare and file VAT returns
• reports:readSee your reports
• projects:readSee your projects
• projects:writeCreate and update projects
• time:readSee time entries
• time:writeRecord and change time entries
• export:readDownload a complete copy of your books

The headline endpoint. Two ways to specify the customer: client_id (existing) or client (inline new). Totals are computed server-side from your line items — don't pass totals; they'll be overwritten.

curl -X POST https://ddmflow.com/api/invoices \
  -H "Authorization: Bearer ddm_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client": { "name": "Acme Corp", "email": "billing@acme.com" },
    "payment_terms": "Net 30",
    "items": [
      { "description": "May consulting", "quantity": 12, "unit_price": 750 },
      { "description": "Project setup", "quantity": 1,  "unit_price": 1500 }
    ]
  }'

{
  "id": "8a9c0b40-…",
  "invoice_number": "INV-007",
  "status": "draft",
  "client": { "name": "Acme Corp", "email": "billing@acme.com" },
  "subtotal": 10500,
  "tax_amount": 1575,
  "total_amount": 12075,
  "currency": "ZAR",
  "due_date": "2026-06-14"
}

Full REST surface — paste this into your editor and let your AI agent discover the rest:

Soft limit: ~120 requests/minute per API key. Hit it and you'll receive HTTP 429 with a rate_limited code. Wait a few seconds and retry.

All errors follow a consistent shape:

{
  "error": {
    "code": "validation_error",
    "message": "client_id is required",
    "details": { "field": "client_id" }
  }
}

Error codes: unauthorized (401), forbidden (403), not_found (404), gone (410, expired portal link), validation_error (422), subscription_required (402, your tier doesn't include this), rate_limited (429), conflict (409), internal_error (500).