Skip to content
API documentation

Connect your books to anything.

A small, plain API; a connector for AI assistants; a Partner API for banks; and imports from the apps businesses already use. Every connection belongs to one business and is switched on by its owner.

What connects today
  • Zoho, QuickBooks, Square, Loyverse, Excel / CSVAvailable

    Import products and customers from a file you export from the other app.

  • APIAvailable

    Read a business's books from your own software; add entries with a key that allows it.

  • AI assistants (MCP)Available

    Let an AI assistant that supports MCP answer questions from the books.

  • WhatsAppAvailable

    Record by message or receipt photo, with a Save button before anything is stored.

  • Banks, microfinance banks and lendersAvailable

    The Partner API: an institution invites its customers and, with each owner's approval, reads their financial health and loan readiness.

  • Live sync with invoicing appsPlanned

    Two-way sync with Zoho Books and QuickBooks, without exporting files. Each provider must approve the connection first.

  • Bank statements and bank feedsPlanned

    Upload a statement and match it to the books; then a direct, consented connection through a licensed open-banking provider.

Step 1

Get an access key

The business owner signs in, opens Connect other apps, and creates a key. It is shown once and starts with bsk_. A key reads one business's books. It can add entries only if the owner ticked that box, and it can be switched off at any time.

Send it with every request. Each key is limited to 120 requests a minute.

Authorization: Bearer bsk_your_key_here
The API

Eight addresses. Plain JSON.

Base address: https://business-stewards.com/api/v1. Amounts are in the business's own currency, given in the currency field.

  • GET/api/v1/summary

    Cash, this month so far, the health score and Steward's findings

  • GET/api/v1/outlook?days=30

    Where cash is heading, and the tightest day

  • GET/api/v1/report?month=2026-10

    One month's health report

  • GET/api/v1/transactions?from=&to=&kind=&limit=

    Entries in the books, newest first

  • POST/api/v1/transactions

    Add a money-in or money-out entry (keys allowed to add entries)

  • GET/api/v1/customers/unpaid

    Who owes the business, and how late

  • GET/api/v1/stock

    Products, and the days of stock left

  • GET/api/v1/loan?months=6&rate=4

    Loan readiness: eligibility, and the amount the records support

Your first two calls

curl https://business-stewards.com/api/v1/summary \
  -H "Authorization: Bearer bsk_your_key_here"
curl -X POST https://business-stewards.com/api/v1/transactions \
  -H "Authorization: Bearer bsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "money_in", "amount": 47500, "account": "cash",
        "category": "Sales", "description": "5 gowns", "date": "2026-11-15" }'

Every address, in full

Each answer below is a real one, from a sample business. Dates are ISO 8601 in UTC; amounts are plain numbers in the business's own currency.

GET/api/v1/summary

The business right now: cash in each account, this month so far against the same days last month, a month-end forecast, what customers owe, the health score and Steward's findings.

Example answer
{
  "business": "Amara Fashion House", "code": "AMA-7K2", "currency": "NGN", "as_of": "2026-11-15T15:32:24.909Z",
  "cash": { "cash_in_hand": 722200, "bank": 500400, "mobile_money": 0, "total": 1222600 },
  "this_month": { "money_in": 311500, "running_costs": 232000, "kept": 79500,
                  "same_days_last_month": { "money_in": 303000, "running_costs": 232000, "kept": 71000 } },
  "month_end_forecast": { "money_in": 623000, "running_costs": 464000, "kept": 159000 },
  "customers_owe": 52000, "owed_to_suppliers": 0, "runway_days": 79,
  "health_score": { "score": 82, "out_of": 100,
    "parts": [ { "name": "Profitability", "points": 17, "out_of": 20, "note": "Net margin 26% — healthy" }, … ] },
  "findings": [ { "level": "good", "title": "Money in is up 3% on last month", "detail": "₦311,500 so far vs ₦303,000 by day 15 last month." } ],
  "entries_recorded": 385
}
GET/api/v1/outlook

Where cash is heading: the expected balance at the end of the period, the tightest day, whether cash is expected to run short, and what is expected in and out.

  • daysHow many days ahead, 7 to 90. Default 30.
Example answer
{
  "currency": "NGN", "days": 30, "cash_today": 1222600, "expected_at_end": 1493450,
  "tightest_point": { "date": "2026-11-15", "balance": 1222600 }, "runs_short": false,
  "expected_in": [ { "what": "Everyday sales", "amount": 625000, "basis": "About ₦20,833 a day, from your last 60 days" },
                   { "what": "Customers due to pay", "amount": 52000, "basis": "1 unpaid balance falling due" } ],
  "expected_out": [ { "what": "Everyday costs", "amount": 406150, "basis": "About ₦13,538 a day on stock and running costs" }, … ],
  "overdue_from_customers_not_counted": 0,
  "balance_by_week": [ { "date": "2026-11-15", "balance": 1222600 }, { "date": "2026-11-22", "balance": 1273665 }, … ],
  "based_on_days_of_records": 60, "early_estimate": false
}
GET/api/v1/report

One calendar month: money in, running costs, what was kept, the month before, cash at month end, the health score, where the money went, and what to do next.

  • monthYYYY-MM, for example 2026-10. Defaults to the last finished month.
Example answer
{
  "month": "2026-10", "label": "October 2026", "currency": "NGN", "has_records": true, "recorded_days": 31, "days_in_month": 31,
  "money_in": 633500, "running_costs": 411800, "kept": 221700, "kept_percent_of_money_in": 35,
  "previous_month": { "money_in": 650500, "running_costs": 417000, "kept": 233500 },
  "cash_at_month_end": 1213100, "customers_owe": 0, "owed_to_suppliers": 0, "owner_withdrawals": 70000,
  "health_score": { "score": 100, "out_of": 100, "parts": [ … ] },
  "where_the_money_went": [ { "category": "Transport", "amount": 84400 }, { "category": "Inventory / materials", "amount": 79300 }, … ],
  "top_customers": [],
  "went_well": [ "You kept ₦221,700 — ₦35 of every ₦100 that came in.", "Cash would cover about 91 days of costs." ],
  "watch": [],
  "do_next": [ "Keep doing what you're doing — and set aside part of what you kept as a reserve." ]
}
GET/api/v1/loan

Loan readiness, from a machine-learning model: eligibility, a readiness score, the loan amount it expects to be repaid, the chance of repaying it on time, and what helped or hurt.

  • monthsRepayment period, 1 to 24. Default 6.
  • rateFlat interest per month, in percent, 0 to 15. Default 4.
Example answer
{
  "business": "Amara Fashion House", "currency": "NGN", "as_of": "2026-11-15T15:31:40.220Z",
  "eligibility": "likely_eligible",
  "headline": "Your records support a loan of about ₦240,000.",
  "readiness_score": { "score": 72, "out_of": 100, "grade": "B" },
  "estimated_amount": 240000, "upper_limit": 480000,
  "chance_of_repaying_on_time_percent": 90, "standard_loan_risk_percent": 13,
  "monthly_repayment": 49600, "total_repayable": 297600,
  "terms": { "months": 6, "monthly_interest_percent": 4, "interest": "flat" },
  "basis": { "days_of_records": 185, "average_monthly_money_in": 629750, "average_monthly_running_costs": 411583.33,
             "average_monthly_owner_withdrawals": 70000, "free_cash_each_month": 148166.67, "cash_today": 1222600, … },
  "factors": [ { "name": "Room to repay", "effect_points": 5, "direction": "helps", "note": "About ₦148,167 a month is left after costs, owner drawings and existing repayments" }, … ],
  "to_improve": [ "Pay yourself a fixed amount each month. You are taking out about ₦70,000 a month." ],
  "model": { "kind": "machine learning", "version": "1.0-sim", "practice_loans": 40000, "real_loans": 0 },
  "note": "A model's estimate from the business's own records. It is not a credit decision or an offer of credit."
}
GET/api/v1/transactions

Entries in the books, newest first.

  • from, toFirst and last day, YYYY-MM-DD.
  • kindmoney_in, money_out, customer_owes, we_owe, stock, owner_invested, owner_withdrew or transfer.
  • limit1 to 500. Default 100.
Example answer
{
  "currency": "NGN", "count": 2, "total_matching": 385,
  "entries": [
    { "id": "…", "date": "2026-11-15T14:00:00.000Z", "kind": "money_out", "amount": 14600, "category": "Packaging",
      "description": null, "account": "bank", "party": null, "item": null, "due_date": null },
    { "id": "…", "date": "2026-11-15T10:00:00.000Z", "kind": "money_in", "amount": 24500, "category": "Sales", "account": "bank", … }
  ]
}
POST/api/v1/transactions

Add one money-in or money-out entry. Needs a key that is allowed to add entries. Money out is refused if the account does not hold enough, and so is a date in the future or before the opening-balance date.

  • kindmoney_in or money_out. Required.
  • amountGreater than zero. Required.
  • accountcash, bank or mobile_money. Default cash.
  • categoryFor example Sales, Transport, Rent. Defaults to Sales or Miscellaneous.
  • description, partyFree text; the customer or supplier, if known.
  • dateYYYY-MM-DD. Defaults to today.
Example answer
HTTP/1.1 201 Created

{
  "ok": true,
  "entry": { "id": "…", "date": "2026-11-15T11:00:00.000Z", "kind": "money_in", "amount": 47500, "category": "Sales",
             "description": "5 gowns", "account": "cash", "party": null },
  "balances": { "cash_in_hand": 769700, "bank": 500400, "mobile_money": 0 }
}
GET/api/v1/customers/unpaid

Who owes the business, biggest first, with how much is overdue and how late the oldest balance is.

Example answer
{
  "currency": "NGN", "total_owed": 52000, "total_overdue": 0,
  "customers": [ { "name": "Mrs Bello", "owes": 52000, "balances": 1, "overdue": 0, "oldest_days_late": 0 } ]
}
GET/api/v1/stock

Finished products: how many are left, their value, how many sold in the last 30 days, and the days of stock left at that pace.

Example answer
{
  "currency": "NGN",
  "products": [ { "item": "Ankara gown", "left": 9, "value": 45000, "sold_last_30_days": 51, "days_of_stock_left": 5, "status": "running low" } ]
}

Errors and limits

Errors come back as { "error": "…" } in plain language, with the usual status codes.

  • 401

    The access key is missing, wrong, or has been switched off.

  • 403

    The key may not do this: a read-only key adding an entry, a paused business, or connected apps switched off for it.

  • 404

    No such address.

  • 422

    An entry was refused. The message says why: not enough in the account, a future date, a locked date.

  • 429

    Too fast: each key is limited to 120 requests a minute. Wait for the seconds given in Retry-After.

  • 503

    The API is not switched on for this installation yet.

This is version 1, and the version is in the address. New fields may be added to answers at any time, so ignore fields you do not recognise; anything that would break a working integration will come as a new version.

AI assistants

Ask an assistant about your own numbers.

Business Steward speaks the Model Context Protocol (MCP), the open standard AI assistants use to reach outside tools. Connect an assistant and ask “How did October go?”, “Who should I chase this week?” or “Can I afford to restock?” — it answers from the business's real books.

Server address
https://business-stewards.com/api/mcp
Sign-in
Authorization: Bearer bsk_…
Transport
Streamable HTTP. Each request stands alone; no session to keep open.
What the assistant can do
  • get_business_summary — Cash, this month, health score and findings
  • get_cash_outlook — The next 30 days of cash, and whether it runs short
  • get_monthly_report — How a month went, and what to do next
  • list_transactions — Entries, filtered by date and kind
  • list_unpaid_customers — Who owes, and how late
  • list_stock — Products and days of stock left
  • get_loan_readiness — Whether the business looks ready for a loan, and how much
  • record_entry — Add money in or out — only with a key that allows it

Typical setup

Most assistants that support MCP take a small settings block like this one:

{
  "mcpServers": {
    "business-steward": {
      "type": "http",
      "url": "https://business-stewards.com/api/mcp",
      "headers": { "Authorization": "Bearer bsk_your_key_here" }
    }
  }
}

Whatever the assistant, it needs the same two things: the server address, and the Authorization header. Use a read-only key unless you want the assistant to record entries for you.

Building something with it?

Start with a read-only key on your own business, and see what your numbers can do elsewhere.