Fedha API

Core Concepts

Multi-tenancy

Every system that uses Fedha API is a tenant. A tenant's data is completely isolated — one tenant cannot see another's accounts, journals, or reports. You get one API key per tenant and include it on every request.

Your App  ──→  POST /journal  (X-API-Key: your-key)  ──→  Fedha API  ──→  Neon DB

Double-entry bookkeeping

Every financial event is recorded as a journal entry with two or more lines. Total debits must always equal total credits. The API enforces this — it rejects any unbalanced request.

Example: Customer pays rent of 500,000 TZS

  DR  Bank Account (1020)       500,000
  CR  Rent Receivable (1110)    500,000

Idempotency

If you post a journal entry with a source_type and source_id, the API remembers it. Posting the same source twice is safe — the old entry is automatically reversed and replaced. Retry on network failure without creating duplicates.

POST /journal  {source_type: "payment", source_id: "pay_123"}  →  creates entry
POST /journal  {source_type: "payment", source_id: "pay_123"}  →  reverses old, creates new

System Labels

Instead of memorising account codes, reference accounts by a label like PRIMARY_BANK or AR_CONTROL. Labels are consistent across all tenants that seeded the same domain, so your integration code is portable.

Authentication

Fedha uses two types of API keys. Keep them separate — the admin key provisions tenants, the tenant key does everything else.

Tenant API Key — for all accounting operations

Used for posting journals, fetching reports, and reconciliation.

X-API-Key: your-tenant-api-key

Admin Key — for provisioning only

Used only when creating tenants or API keys. This key stays on your server and is never shared with client apps.

X-Admin-Key: your-admin-secret-key

Quick Start

From zero to posting your first transaction in 4 steps.

curl -X POST https://fedha-api.com/admin/tenants \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "currency": "TZS"}'

curl -X POST https://fedha-api.com/admin/tenants/{tenant_id}/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

curl -X POST "https://fedha-api.com/accounts/seed?domain=rental" \
  -H "X-API-Key: fapi_xxxxxxxxxxxxxxxx"

curl -X POST https://fedha-api.com/journal \
  -H "X-API-Key: fapi_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-05-20",
    "description": "Rent payment from John Doe",
    "source_type": "payment",
    "source_id": "pay_001",
    "lines": [
      {"account_label": "PRIMARY_BANK", "debit": 500000, "credit": 0},
      {"account_label": "AR_CONTROL",   "debit": 0,      "credit": 500000}
    ]
  }'

Admin — Tenants & API Keys

All admin endpoints require the X-Admin-Key header.

Create a tenant

List all tenants

Get a single tenant

Deactivate a tenant

Sets is_active: false. Does not delete data.

Create an API key

List API keys for a tenant

Revoke an API key

Sets is_active: false. Requests using this key will immediately receive 401.

Chart of Accounts

All endpoints require X-API-Key header.

Seed a full Chart of Accounts

Create a custom account

List accounts

Get / Update an account

Rental Domain — Full Account List

Journal Entries

The core of Fedha API. Every financial event — a payment, an expense, an invoice — becomes a journal entry.

Post a journal entry

Each line in lines:

Common Journal Patterns

{
  "date": "2026-05-01",
  "description": "Rent invoice — Unit 3A — May 2026",
  "source_type": "invoice",
  "source_id": "inv_001",
  "lines": [
    {"account_label": "AR_CONTROL",   "debit": 750000, "credit": 0},
    {"account_label": "RENT_REVENUE", "debit": 0,      "credit": 750000}
  ]
}

{
  "date": "2026-05-10",
  "description": "Rent payment — Unit 3A — John Doe",
  "source_type": "payment",
  "source_id": "pay_001",
  "lines": [
    {"account_label": "PRIMARY_BANK", "debit": 750000, "credit": 0},
    {"account_label": "AR_CONTROL",   "debit": 0,      "credit": 750000}
  ]
}

{
  "date": "2026-05-10",
  "description": "M-Pesa rent payment — Unit 3A",
  "source_type": "payment",
  "source_id": "pay_002",
  "lines": [
    {"account_label": "MPESA",      "debit": 750000, "credit": 0},
    {"account_label": "AR_CONTROL", "debit": 0,      "credit": 750000}
  ]
}

{
  "date": "2026-05-15",
  "description": "Plumbing repair — Block B",
  "source_type": "expense",
  "source_id": "exp_001",
  "lines": [
    {"account_label": "MAINTENANCE_EXPENSE", "debit": 120000, "credit": 0},
    {"account_label": "PRIMARY_BANK",        "debit": 0,      "credit": 120000}
  ]
}

{
  "date": "2026-05-01",
  "description": "Security deposit — Unit 3A — John Doe",
  "source_type": "deposit",
  "source_id": "dep_001",
  "lines": [
    {"account_label": "PRIMARY_BANK",              "debit": 1000000, "credit": 0},
    {"account_label": "SECURITY_DEPOSIT_LIABILITY", "debit": 0,       "credit": 1000000}
  ]
}

{
  "date": "2026-05-31",
  "description": "Security deposit refund — Unit 3A — John Doe vacated",
  "source_type": "deposit_refund",
  "source_id": "ref_001",
  "lines": [
    {"account_label": "SECURITY_DEPOSIT_LIABILITY", "debit": 1000000, "credit": 0},
    {"account_label": "PRIMARY_BANK",               "debit": 0,       "credit": 1000000}
  ]
}

Reverse a journal entry

List journal entries

The response is wrapped in a pagination envelope:

{
  "items": [...],
  "total": 142,
  "has_more": true,
  "next_cursor": "eyJkYXRlIjogIjIwMjYtMDUtMTAiLCAiY3JlYXRlZF9hdCI6IC..."
}

Pass next_cursor as cursor on the next request to fetch the next page.

Get a single journal entry

Financial Reports

All report endpoints require X-API-Key and return structured JSON.

Trial Balance

All accounts with their net debit/credit balances for the period. Used to verify the books balance.

Income Statement (P&L)

Revenue and expenses for a period, resulting in net income.

Balance Sheet

Assets, liabilities, and equity as of a specific date. Net income is folded into equity automatically.

Cash Position

Sum of all cash and bank account balances. Perfect for a quick dashboard widget.

AR Aging Report

Outstanding receivables bucketed by age. Essential for following up on overdue rent.

VAT Return

Computes output VAT (collected from customers) and input VAT (paid to suppliers) for a period, with the net amount payable to TRA.

Output VAT is sourced from credits to VAT_PAYABLE (2030). Input VAT is sourced from debits to INPUT_VAT (1130). If is_refund: true, input exceeds output and TRA owes you a refund.

{
  "period_start": "2026-05-01",
  "period_end": "2026-05-31",
  "vat_rate": "0.18",
  "filing_deadline": "2026-06-20",
  "taxable_sales": 1000000,
  "output_vat": 180000,
  "taxable_purchases": 200000,
  "input_vat": 36000,
  "net_vat_payable": 144000,
  "is_refund": false,
  "output_lines": [...],
  "input_lines": [...]
}

Bank Reconciliation

Match your accounting records against your bank statement to ensure no transactions are missing or duplicated.

Workflow

Create a reconciliation

List lines / Toggle / Lock

A locked reconciliation returns 409 Conflict if you try to toggle lines.

Webhooks

Get real-time notifications when accounting events occur. Register a URL and Fedha will POST a signed JSON payload every time a matching event fires.

Events

Register a webhook endpoint

curl -X POST https://fedha-api.com/webhooks \
  -H "X-API-Key: fapi_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/hooks/fedha", "events": ["journal.posted", "journal.reversed"]}'

Manage webhooks

The deliveries endpoint shows HTTP status, response time, success flag, and error messages for each delivery attempt.

Verifying webhook signatures

Every request from Fedha includes an X-Fedha-Signature: sha256=<hex> header. Always verify it before processing.

import hmac, hashlib

def verify_fedha_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# In your webhook handler:
sig = request.headers.get("X-Fedha-Signature", "")
if not verify_fedha_webhook(request.body, sig, FEDHA_WEBHOOK_SECRET):
    return 401

const crypto = require("crypto");

function verifyFedhaWebhook(payload, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader)
  );
}

Payload shape

{
  "event": "journal.posted",
  "tenant_id": "tenant-uuid",
  "data": {
    "id": "entry-uuid",
    "date": "2026-05-20",
    "description": "Rent payment — Unit 3A",
    "source_type": "payment",
    "source_id": "pay_001",
    "lines": [...]
  }
}

Error Reference

Common Mistakes

Code Examples

import os
import requests

BASE_URL = "https://fedha-api.com"
API_KEY  = os.environ["FEDHA_API_KEY"]

def post_journal(date, description, source_type, source_id, lines):
    response = requests.post(
        f"{BASE_URL}/journal",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "date": str(date),
            "description": description,
            "source_type": source_type,
            "source_id": str(source_id),
            "lines": lines,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

def void_journal(source_type, source_id):
    response = requests.delete(
        f"{BASE_URL}/journal/reverse",
        headers={"X-API-Key": API_KEY},
        params={"source_type": source_type, "source_id": str(source_id)},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

def get_cash_position(as_of_date):
    response = requests.get(
        f"{BASE_URL}/reports/cash-position",
        headers={"X-API-Key": API_KEY},
        params={"as_of_date": str(as_of_date)},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

# Usage
post_journal(
    date="2026-05-20",
    description="Rent payment — Unit 3A",
    source_type="payment",
    source_id="pay_001",
    lines=[
        {"account_label": "PRIMARY_BANK", "debit": 750000, "credit": 0},
        {"account_label": "AR_CONTROL",   "debit": 0,      "credit": 750000},
    ]
)

const BASE_URL = "https://fedha-api.com";
const API_KEY  = process.env.FEDHA_API_KEY;

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

async function postJournal({ date, description, sourceType, sourceId, lines }) {
  const res = await fetch(`${BASE_URL}/journal`, {
    method: "POST", headers,
    body: JSON.stringify({ date, description,
      source_type: sourceType, source_id: String(sourceId), lines }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function voidJournal(sourceType, sourceId) {
  const params = new URLSearchParams({ source_type: sourceType, source_id: String(sourceId) });
  const res = await fetch(`${BASE_URL}/journal/reverse?${params}`, { method: "DELETE", headers });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

// Usage
await postJournal({
  date: "2026-05-20", description: "Rent payment — Unit 3A",
  sourceType: "payment", sourceId: "pay_001",
  lines: [
    { account_label: "PRIMARY_BANK", debit: 750000, credit: 0 },
    { account_label: "AR_CONTROL",   debit: 0,      credit: 750000 },
  ],
});

<?php
define('BASE_URL', 'https://fedha-api.com');
define('API_KEY', getenv('FEDHA_API_KEY'));

function fedha_post(string $path, array $body): array {
    $ch = curl_init(BASE_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($body),
        CURLOPT_HTTPHEADER     => ['X-API-Key: ' . API_KEY, 'Content-Type: application/json'],
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

fedha_post('/journal', [
    'date' => '2026-05-20', 'description' => 'Rent payment — Unit 3A',
    'source_type' => 'payment', 'source_id' => 'pay_001',
    'lines' => [
        ['account_label' => 'PRIMARY_BANK', 'debit' => 750000, 'credit' => 0],
        ['account_label' => 'AR_CONTROL',   'debit' => 0,      'credit' => 750000],
    ],
]);