Skip to content
Partner API · for banks, microfinance banks and lenders

Give your customers Business Steward. See their real numbers.

Invite your business customers from your own systems. Each owner approves on their own screen; from then on you can read that business's financial health, cash outlook and loan readiness — worked out from records the owner keeps every day.

Version 1 · REST and JSON · test mode with sample businesses · signed webhooks

Overview

What you can do

Business Steward is where a small business keeps its books: every sale, expense, credit and stock movement, recorded in the app or by WhatsApp message. From those records it works out a health score, a 30-day cash outlook and a loan readiness estimate. The Partner API lets an institution bring its customers onto Business Steward and, with their permission, use those figures in its own lending and relationship work.

  • Onboard customers

    Send an invitation from your core banking system, CRM or loan-origination tool. The customer signs up or signs in, and approves.

  • Assess loan readiness

    Eligibility, a score out of 100 and the loan amount the records support — with the monthly averages behind every figure.

  • Watch financial health

    Cash position, this month against last, a health score in five parts, and a 30-day cash outlook.

  • Pay for their access

    Optionally cover the subscription of every business connected to you, so your customers use Business Steward at no cost to them.

Three rules shape everything below. You never see a business that has not approved you. You see only the kinds of record the owner approved. Either side can end the connection at any moment, and access stops at once.

The flow

How it works

  1. You invite a customer

    Call POST /customers with your own customer number and the kinds of record you are asking for. You get back a link and an 8-character code.

  2. You send them the link

    By SMS, WhatsApp, email or in your own app. If they are new to Business Steward they create a free account first; the invitation waits for them.

  3. The owner approves on their own screen

    They see your institution's name and, in plain words, exactly what you will be able to see. They press Approve or Decline.

  4. You are told

    A signed webhook arrives (customer.approved), or you ask with GET /customers/{id}. The status is now active.

  5. You read their records

    Summary, loan assessment, cash outlook, monthly report or individual entries — whichever scopes were approved — for as long as the connection lasts.

Before you start

Getting access

Partner accounts are opened by Business Steward, not self-service. Write to us with your institution's name, what you plan to build and a technical contact. You receive a test key first, and a live key once your integration has been checked against the go-live list.

  • bsp_test_…test key

    Works on sample businesses only. Never touches a real customer. Use it to build and to run your automated tests.

  • bsp_live_…live key

    Works on real customers, each of whom must approve. Keep it on your servers; never put it in a mobile app or a web page.

A key is shown once, when it is made; we store only a fingerprint of it. If one is exposed, tell us and it is switched off and replaced. You may hold several keys at once, so a key can be rotated without downtime.

Every request

Authentication

Send the key in the Authorization header of every request, over HTTPS. The base address is the same for test and live — the key decides which.

Base address   https://business-stewards.com/api/partner/v1
Header         Authorization: Bearer bsp_test_your_key_here
curl https://business-stewards.com/api/partner/v1/me \
  -H "Authorization: Bearer bsp_test_your_key_here"
{
  "object": "partner",
  "id": "5b1f6f0e-2c8e-4d6a-9d3e-0a4c1f2b7e90",
  "name": "Unity Microfinance Bank",
  "kind": "mfb",
  "mode": "test",
  "covers_subscription": true,
  "webhook_configured": true,
  "rate_limit_per_minute": 300
}

Every response carries an X-Steward-Mode header (test or live), so your logs always show which world a call ran in. Requests and responses are JSON, in UTF-8. Dates are ISO 8601 in UTC. Amounts are plain numbers in the business's own currency, named in currency.

Build without real customers

Test mode

With a test key, every customer you invite is a sample business. There are four, one for each answer you will meet in production. Choose one with the sample field when you invite; leave it out and one is picked from your customer number (the same number always gets the same sample).

  • strongsample

    Amara Fashion House, Lagos. Six months of steady records. Likely to qualify.

  • borderlinesample

    Tunde Provisions Store, Ibadan. Four months of records, thin margins and an overdue supplier bill. Borderline.

  • weaksample

    Kemi Beauty Supplies, Abuja. Five months of records, spending more than it takes in. Not ready.

  • newsample

    Ngozi Foods, Enugu. Six weeks of records. Still building a track record.

No real person answers a test invitation, so you stand in for the owner with POST /customers/{id}/simulate and an action of approve, decline or revoke. Webhooks fire exactly as they do live, with "mode": "test". Sample figures are made up, always end today, and are the same every time you ask on the same day.

Ten minutes

Quick start

1. Invite a customer. external_ref is your own customer number; it is how you find them again.

curl -X POST https://business-stewards.com/api/partner/v1/customers \
  -H "Authorization: Bearer bsp_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "external_ref": "CUST-004512", "business_name": "Amara Fashion House",
        "owner_name": "Amara Okafor", "phone": "+2348012345678",
        "scopes": ["summary", "loan"], "sample": "strong" }'
HTTP/1.1 201 Created

{
  "id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
  "object": "customer",
  "mode": "test",
  "external_ref": "CUST-004512",
  "status": "pending",
  "scopes": ["summary", "loan"],
  "business": null,
  "invited": { "business_name": "Amara Fashion House", "owner_name": "Amara Okafor", "phone": "+2348012345678", "email": null },
  "invite_code": "K7QM2XPD",
  "invite_url": "https://business-stewards.com/link/K7QM2XPD",
  "subscription_covered": false,
  "created_at": "2026-11-16T09:12:44.118Z",
  "expires_at": "2026-12-16T09:12:44.118Z",
  "decided_at": null, "ended_at": null, "ended_by": null
}

2. Approve it (in test mode you do this yourself; live, the owner does it on their phone).

curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/simulate \
  -H "Authorization: Bearer bsp_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "approve" }'

3. Read the loan assessment.

curl "https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loan-assessment?months=6&rate=4" \
  -H "Authorization: Bearer bsp_test_your_key_here"

The full response is shown under Reading records.

Reference

Customers

A customer is one invitation and the connection that follows from it. All addresses below start with https://business-stewards.com/api/partner/v1.

  • GET/me
    no scope

    Who the key belongs to, and whether it is a test or live key

  • POST/customers
    no scope

    Invite a customer; returns the link to send them

  • GET/customers
    no scope

    List your customers, newest first

  • GET/customers/{id}
    no scope

    One customer, and where the invitation stands

  • DELETE/customers/{id}
    no scope

    Withdraw an invitation or end a connection

  • GET/customers/{id}/summary
    summary

    Cash, this month so far, health score

  • GET/customers/{id}/loan-assessment
    loan

    Eligibility, readiness score, supported loan amount

  • GET/customers/{id}/outlook
    cashflow

    Where cash is heading over the next 7–90 days

  • GET/customers/{id}/report
    cashflow

    One calendar month's health report

  • GET/customers/{id}/transactions
    transactions

    Individual entries, newest first

  • POST/customers/{id}/loans
    loan

    Tell us about a loan you gave this customer

  • GET/customers/{id}/loans
    no scope

    Loans you have reported for this customer

  • POST/customers/{id}/loans/{loan_ref}
    no scope

    Tell us how the loan went

  • POST/customers/{id}/simulate
    no scope

    Test keys only: approve, decline or disconnect as the owner

Invite a customer — POST /customers

  • external_refstring, required

    Your own customer number, up to 80 characters. You can have one open invitation or connection per number.

  • scopeslist of strings

    What you are asking the owner to share: summary, cashflow, loan, transactions. Default: summary and loan. Ask only for what you will use — a shorter list is approved more often.

  • business_namestring

    Shown to the owner on the approval screen, so they recognise the invitation. Up to 120 characters.

  • owner_namestring

    For your own reference. Up to 120 characters.

  • phone / emailstring

    For your own reference. Business Steward does not send the invitation for you — you send the link.

  • samplestring

    Test keys only: strong, borderline, weak or new.

Safe to repeat. Sending the same external_ref again returns the invitation that is already open, with status 200 rather than 201, so a retry after a timeout never creates a duplicate. Once an invitation is declined, revoked or expired, the same number can be invited afresh.

The link and the code. invite_url opens the approval screen directly. invite_code is the same thing in eight characters, for an owner who would rather type it: in the app, Connect other apps → Have an invitation code from your bank? An invitation lasts 30 days.

Statuses

  • pendingstatus

    Invited. Waiting for the owner to answer. Nothing can be read.

  • activestatus

    The owner approved. Records can be read, for the scopes approved.

  • declinedstatus

    The owner said no. Nothing was shared.

  • revokedstatus

    Ended — by the owner, or by you (DELETE). ended_by says which.

  • expiredstatus

    Not answered within 30 days. Invite again to send a fresh link.

List customers — GET /customers

  • statusquery

    Only customers in this status.

  • external_refquery

    Find a customer by your own number.

  • limitquery

    1 to 100. Default 25.

  • starting_afterquery

    The id of the last customer on the previous page.

{ "object": "list", "data": [ { "id": "…", "object": "customer", … } ], "has_more": true }

To read every customer, keep asking with starting_after set to the last id you received, until has_more is false.

End a connection — DELETE /customers/{id}

Withdraws a pending invitation or ends an active connection. You stop being able to read the business immediately, and if you were covering its subscription, that ends too. The customer is returned with status revoked and ended_by: "partner".

Each scope is shown to the owner in these exact words before they decide. A request for a scope that was not approved is refused with 403 scope_not_granted; to add a scope later, end the connection and invite again with the longer list.

  • summaryscope

    Business summary. Your cash position, this month's money in and running costs, what customers owe you, and your health score.

  • cashflowscope

    Cash outlook and monthly reports. Where your cash is heading over the next 30 days, and how each month went.

  • loanscope

    Loan readiness. Your readiness score and the loan amount your records support, with the monthly averages behind it. If it gives you a loan, it may tell Business Steward how the loan went, which helps make these estimates more accurate.

  • transactionsscope

    Individual entries. Each sale, expense, credit and stock entry you have recorded, with its date, amount and description.

Never shared, whatever was approved: the owner's login, password or PIN; staff logins; and their customers' phone numbers. The API is read-only — a partner cannot add, change or delete anything in a business's books.

The owner can see every institution connected to their business under Connect other apps, with what each can see, and disconnect any of them with one tap. You are told by webhook (customer.revoked, ended_by: "owner").

Reference

Reading records

Records are available only while the customer is active; otherwise the answer is 409 customer_not_active. Every record response starts with customer_id and your external_ref, so it can be filed without a second lookup.

Loan assessment — GET /customers/{id}/loan-assessment

  • monthsquery

    Repayment period, 1 to 24. Default 6.

  • ratequery

    Flat interest per month, in percent, 0 to 15. Default 4. Set both to your own product's terms and the amounts follow.

{
  "customer_id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
  "external_ref": "CUST-004512",
  "business": "Amara Fashion House",
  "code": "SAMPLE-1",
  "currency": "NGN",
  "as_of": "2026-11-16T09:14:02.337Z",
  "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, "days_needed": 90, "days_with_entries_percent": 100,
    "average_monthly_money_in": 629750,
    "average_monthly_running_costs": 411583.33,
    "average_monthly_owner_withdrawals": 70000,
    "existing_monthly_loan_repayments": 0,
    "free_cash_each_month": 148166.67,
    "cash_today": 1222600,
    "owed_to_suppliers": 0, "customers_owe": 52000, "customers_overdue": 0,
    "loans_received_in_period": 0
  },
  "factors": [
    { "name": "Track record",   "effect_points": 0, "direction": "neutral", "note": "About 6 months of records · entries on 100% of days" },
    { "name": "Steady sales",   "effect_points": 3, "direction": "helps",   "note": "Sales are steady week to week" },
    { "name": "Room to repay",  "effect_points": 5, "direction": "helps",   "note": "About ₦148,167 a month is left after costs, owner drawings and existing repayments" },
    { "name": "Cash cushion",   "effect_points": 2, "direction": "helps",   "note": "Cash on hand covers about 89 days of costs" },
    { "name": "Existing debts", "effect_points": 3, "direction": "helps",   "note": "No supplier debt or loan repayments recorded" }
  ],
  "strengths": [ "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." ],
  "blockers": [],
  "monthly_history": [ { "period": "20 May – 18 Jun", "money_in": 625000, "running_costs": 403000, "left": 222000 }, … ],
  "model": { "kind": "machine learning", "version": "1.0-sim", "trained": "2026-11-15", "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."
}
  • eligibilitystring

    likely_eligible, borderline, not_yet, or building_history (fewer than 90 days of records).

  • readiness_scoreobject

    The model's odds that the business repays a standard loan without trouble, on a 0–100 scale (50 is even odds, 76 is nine-to-one). Grades: A is 80 and above, B 67–79, C 55–66, D below 55.

  • estimated_amountnumber

    The largest loan, on the terms asked for, that the model expects to be repaid without trouble at least nine times in ten. 0 when not_yet or building_history.

  • upper_limitnumber

    The same at eight times in ten. Treat as a ceiling, not a target.

  • chance_of_repaying_on_time_percentinteger

    The model's estimate for estimated_amount.

  • standard_loan_risk_percentinteger

    The chance of repayment trouble on the standard loan the score is judged on: half a month's money in, over six months at 4% a month.

  • monthly_repaymentnumber

    The repayment on estimated_amount; total_repayable is the amount plus interest.

  • provisional_amountnumber

    Only while building_history: where the estimate stands so far. Not to be lent against.

  • basisobject

    The monthly averages the model's inputs are built from, taken over up to six months of records.

  • factorslist

    What moved the score, in five groups. effect_points is the exact number of score points the group added or took off against a typical business.

  • to_improvelist

    The advice the owner is shown in their own app, drawn from what is pulling their score down hardest.

  • blockerslist

    Plain reasons behind a not_yet, such as nothing being left each month to repay from.

  • monthly_historylist

    Money in, running costs and what was left for each complete 30-day period, oldest first.

  • modelobject

    Which model produced the answer, and how many practice and real loans it has learned from. See the model section below.

Summary — GET /customers/{id}/summary

{
  "customer_id": "0f6c1a52-…", "external_ref": "CUST-004512",
  "business": "Amara Fashion House", "code": "SAMPLE-1", "currency": "NGN", "as_of": "2026-11-16T09:14:40.902Z",
  "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
}

The health score has five parts of 20 points each: profitability, cash position, debt exposure, customer debt and owner withdrawals. It describes this month; the loan readiness score looks back up to six months. They answer different questions and will usually differ.

Cash outlook, monthly report and entries

  • /outlook?days=30cashflow

    Cash today, the expected balance at the end of the period (7 to 90 days), the tightest day and its date, whether cash is expected to run short, and the expected money in and out with the basis for each line.

  • /report?month=2026-10cashflow

    One calendar month: money in, running costs, what was kept, the month before for comparison, cash at month end, health score, where the money went, top customers, what went well, what to watch and what to do next. Defaults to the last finished month.

  • /transactionstransactions

    Individual entries, newest first. Filters: from, to (YYYY-MM-DD), kind (money_in, money_out, customer_owes, we_owe, stock, owner_invested, owner_withdrew, transfer) and limit (1 to 500, default 100).

Field-by-field definitions for every response are in the OpenAPI file.

How the estimate is made

The loan readiness model

The assessment comes from a machine-learning model. For one business and one loan it estimates a single thing: the chance of repayment trouble — two or more missed instalments, or money still owed at the end. Every figure in the response is read off that estimate. It uses only the owner's own records: no bureau file, no BVN lookup, no device data. Your own credit policy, identity checks and bureau search still apply, and the decision is yours.

What it has learned from — please read this first

Version 1.0-sim has not yet learned from a real loan. No Business Steward business had a recorded loan outcome when it was built, so it was taught on 40,000 practice businesses: day-by-day simulations with swinging sales, slow spells, rent, a household that is fed first, customers who pay late, suppliers who cut off late payers, and owners who do not record everything. The practice world was set so that conventionally sized loans go wrong about one time in ten. Until model.real_loans is well above zero, treat its figures as a structured second opinion, not as a validated scorecard.

How it did on loans it had never seen

  • Tested on8,000 loans

    One loan in five was kept back from training and used only for testing.

  • Telling good from badAUC 0.884

    1.0 would be perfect and 0.5 a coin toss.

  • Its stated oddscalibrated

    When it said about 9.4%, 9.0% went wrong; when it said about 36%, 40% did.

  • Against fixed rules1.1% vs 12%

    Lending to the same number of applicants as a fixed rule (repayment up to 35% of what is left each month), this share of the model's loans ran into trouble, against the rule's.

These figures show the model has learned the practice world well. They do not show how it performs on real borrowers — that can only be known once real loans have been made and have finished.

What it measures

Fifteen measurements, all of them ratios, so a kiosk and a wholesaler — in naira or in dollars — are measured on the same scale. They are taken from up to the last 180 days of records.

  • Track recordhistory_days, active_share

    How long the record is, and on what share of days there are entries.

  • Steady salesinflow_cv, trend, neg_weeks, worst_month

    How much weekly money-in swings, which way it is heading, how often more went out than came in, and how bad the worst month was.

  • Room to repayop_margin, drawings

    What trading leaves before the owner's drawings, and how much the owner takes out. Books that show almost no drawings are treated as incomplete.

  • Cash cushioncover_days

    Days of running costs the cash on hand would cover — capped at 60, so a large balance (the easiest figure in a set of books to get wrong) cannot buy a larger estimate.

  • Existing debtssup_debt, overdue_recv, existing_repay

    Unpaid supplier bills, customers paying late, and loan repayments already being made, each against monthly money in.

  • The loan itselfburden_free, burden_inflow, tenor

    The monthly repayment against what is left each month and against money in, and the number of months.

Why this kind of model

It is an additive boosted model: one learned curve for each measurement, added together. That was chosen over a black box for one reason — every answer can be explained exactly. The effect_points in factors are not an approximation; they are each group's actual share of the score. Curves are held to one direction where the direction is not in doubt, so a larger repayment can never be scored as safer.

From the model to the figures

  • readiness_score0–100

    The odds of no trouble on a standard loan (half a month's money in, six months, 4% a month), on the scale used for lending scorecards: every 12 points multiplies the odds by about 2.7.

  • estimated_amountrisk ≤ 10%

    The largest loan, on the terms you ask about, whose chance of trouble is 10% or less.

  • upper_limitrisk ≤ 20%

    The largest loan whose chance of trouble is 20% or less.

  • likely_eligibleeligibility

    An estimated amount exists, and the standard loan's risk is 20% or less.

  • borderlineeligibility

    Some loan stays within 20% risk, but the business does not meet the line above. The amount quoted is the cautious end.

  • not_yeteligibility

    Not even a loan of 5% of a month's money in stays within 20% risk — or no money in is recorded.

  • building_historyeligibility

    Fewer than 90 days of records: too little to judge, whatever the model says.

Three guardrails are not learned. No amount is given under 90 days of records. A repayment is never set above what the books show is left each month. And the risk can only rise with the size of the loan.

How it gets better

By learning from what actually happened. When you report a loan and, later, how it went, the business's measurements on the day of the loan are kept with the outcome, and the model is trained again on real results. The model field in every response says which version answered and how many real loans it has learned from; the -sim at the end of the version name goes once it has learned from any.

Its limits. The figures are only as complete as the owner's recording. A business that records only its good days will look better than it is; compare days_with_entries_percent and, where you hold it, the account turnover you can see yourself.

Close the loop

Reporting loans

Two calls per loan: one when you give it, one when it ends. This is optional, and it is the single most useful thing a partner can do — it is what turns a model taught on practice loans into one that knows your borrowers.

When you give a loan — POST /customers/{id}/loans

  • loan_refstring, required

    Your own loan number, up to 80 characters. Sending it again returns the loan already recorded.

  • amountnumber, required

    The principal, in the business's own currency.

  • monthsinteger, required

    1 to 60.

  • monthly_interest_percentnumber, required

    Flat interest per month, 0 to 30.

  • disbursed_ondate

    YYYY-MM-DD. Defaults to today.

curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loans \
  -H "Authorization: Bearer bsp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "loan_ref": "LN-2026-00871", "amount": 250000, "months": 6,
        "monthly_interest_percent": 4, "disbursed_on": "2026-11-20" }'
HTTP/1.1 201 Created

{
  "object": "loan",
  "loan_ref": "LN-2026-00871",
  "customer_id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
  "external_ref": "CUST-004512",
  "mode": "live",
  "amount": 250000, "months": 6, "monthly_interest_percent": 4, "disbursed_on": "2026-11-20",
  "status": "active", "missed_instalments": null, "closed_on": null,
  "predicted_risk_percent": 11, "model_version": "1.0-sim",
  "created_at": "2026-11-20T10:02:11.402Z", "updated_at": "2026-11-20T10:02:11.402Z"
}

The connection must be active and include the loan scope, because the business's measurements are taken that day. Only the fifteen measurements are stored with the loan — ratios, with nothing that names the business. predicted_risk_percent is what the model said at that moment, kept so it can be checked against what happens.

When it ends — POST /customers/{id}/loans/{loan_ref}

  • statusstring, required

    active, repaid, repaid_late, defaulted or written_off.

  • missed_instalmentsinteger

    How many instalments were missed over the life of the loan.

  • closed_ondate

    YYYY-MM-DD.

curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loans/LN-2026-00871 \
  -H "Authorization: Bearer bsp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "repaid", "missed_instalments": 0, "closed_on": "2027-05-20" }'

You can send this more than once as a loan's standing changes, and after the connection has ended. For learning, a loan counts as troubled if it is defaulted or written_off, or had two or more missed instalments. GET /customers/{id}/loans lists what you have reported. Owners are told, on the approval screen, that a lender may report how a loan went.

Be told, don't ask

Webhooks

Give us an HTTPS address and we send it a POST whenever an owner answers or a connection ends. You receive a signing secret (whsec_…) to check that each message really came from Business Steward.

  • customer.approvedevent

    The owner approved. The customer is now active and its business details are included.

  • customer.declinedevent

    The owner declined. Nothing was shared.

  • customer.revokedevent

    The owner disconnected (ended_by: owner). Ending it yourself with DELETE sends no event.

POST /your/webhook/address
Content-Type: application/json
X-Steward-Event: customer.approved
X-Steward-Signature: t=1794822764,v1=5d1c0e6b…c41a

{
  "id": "evt_3f9c1b7a52e04d6c8a1f0b2d4e6a8c90",
  "type": "customer.approved",
  "mode": "live",
  "created_at": "2026-11-16T09:12:44.118Z",
  "data": { "customer": { "id": "0f6c1a52-…", "external_ref": "CUST-004512", "status": "active", … } }
}

Checking the signature

Take the timestamp t and the raw request body, exactly as received. Compute HMAC-SHA256 of t + "." + body with your signing secret, in hex, and compare it with v1. Reject the message if they differ, or if t is more than five minutes old.

// Node.js
const crypto = require("crypto");

function isFromSteward(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;           // too old
  const expected = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
# Python
import hmac, hashlib, re, time

def is_from_steward(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m.group(2))

Delivery. Each event is sent once, and we wait five seconds for any 2xx answer. There are no automatic retries in this version, so treat webhooks as a prompt rather than the record: if your endpoint was down, GET /customers?status=active always shows the truth. Every event carries its own id, for your records. The address must be public HTTPS; redirects are not followed.

When things go wrong

Errors and limits

Errors always have the same shape. Build on code, which will not change; show or log message, which may be reworded.

HTTP/1.1 409 Conflict

{ "error": { "code": "customer_not_active", "message": "The owner has not approved this connection yet." } }
  • 400invalid_json

    The body is not a JSON object.

  • 401missing_key

    No Authorization header.

  • 401invalid_key

    The key is wrong, switched off, or of the wrong kind.

  • 403partner_suspended

    Your partner account is suspended.

  • 403scope_not_granted

    The owner did not approve this kind of record.

  • 403customer_unavailable

    The business is paused, or is not a business account.

  • 403test_only

    simulate was called with a live key.

  • 404customer_not_found

    No such customer for this key. Test and live customers are separate.

  • 404not_found

    No such address.

  • 405method_not_allowed

    That address does not take that method.

  • 409customer_not_active

    The owner has not approved yet, or the connection has ended.

  • 409not_pending

    The invitation was already answered or has expired.

  • 409not_open

    The connection had already ended.

  • 404loan_not_found

    No loan with that loan_ref for this customer.

  • 422invalid_request

    A field is missing or wrong. The message says which.

  • 429rate_limited

    Too many requests. Wait for the seconds given in Retry-After.

  • 500server_error

    Something failed on our side. Safe to try again.

  • 503not_available

    The partner API is not switched on.

Rate limit. 300 requests a minute for each key. Beyond that the answer is 429 with a Retry-After header in seconds; wait, then carry on. For a nightly refresh of a large book, spread the calls out rather than sending them in one burst.

Retrying. GET and DELETE are safe to repeat. POST /customers is safe to repeat for the same external_ref. On a 500 or a network timeout, wait a few seconds and try again, doubling the wait each time.

Versions. This is version 1, and the version is in the address. New fields may be added to responses at any time, so ignore fields you do not recognise. Anything that would break a working integration — removing a field, changing a meaning — will come as a new version, with notice and both running side by side.

Commercial

Paying for your customers

Business Steward is free for a business's first 6 months and then paid by subscription (pricing). An institution can instead agree to cover its customers. When that is switched on for your account, /me shows covers_subscription: true, the owner is told on the approval screen, and every business that connects to you uses Business Steward at no cost to them for as long as the connection lasts.

Each covered customer shows subscription_covered: true. Cover ends when the connection ends, from either side, and the business goes back to its own arrangement. Terms are agreed with us directly — ask.

Trust

Security and data

  • Consent is recorded, and can be withdrawn

    A connection exists only because an owner pressed Approve, and the time is kept. The owner can withdraw at any moment; access stops with the next request.

  • Least access

    You ask for named scopes; the owner sees them in plain words; nothing outside them is ever returned. The API cannot change a business's books.

  • Keys

    Keys are stored as a SHA-256 fingerprint, never in the clear, and can be switched off instantly. Test and live are separate keys and separate customers.

  • Transport

    HTTPS only. Webhooks are signed with HMAC-SHA256 and sent only to public HTTPS addresses.

  • Your side of it

    Keep live keys on your servers. Store only what you need, for as long as you need it. When an owner disconnects, stop using what you hold beyond what your own legal duties require.

How Business Steward itself handles personal information is set out in the privacy policy.

Checklist

Going live

Before a live key is issued, we ask you to confirm each of these against test mode.

  1. 01You invite a customer and store the id against your own customer number.
  2. 02Your message to the customer explains who Business Steward is and why you are asking, and carries the invite link.
  3. 03You handle all five statuses, including declined and expired, without treating them as errors.
  4. 04You handle a strong, a borderline, a weak and a new business — the four samples — sensibly in your own screens.
  5. 05You check the webhook signature, and still work when a webhook is missed.
  6. 06You handle 409 customer_not_active and 403 scope_not_granted when reading records: an owner can disconnect at any time.
  7. 07You back off on 429 and retry on 500.
  8. 08Live keys are held on your servers only, with a named person responsible for rotating them.

Ready to start?

Tell us who you are and what you want to build, and we will reply by email.