Getting started
Your keys
BasePipe gives you two kinds of key. Keep both on your server; never put them in an app or a web page.
bp_test_… | Practice. Works only on practice businesses. Nothing here is real, so build and test freely. |
bp_live_… | Live. Works only on live businesses. Issued when you go live. |
Your first test key comes from BasePipe when you're set up. After that, your admin screen makes and revokes keys under API keys.
Your first call
The API lives at https://api.basepipe.io. Send JSON, and your key in the Authorization header.
curl https://api.basepipe.io/v1/businesses \
-H "Authorization: Bearer bp_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Al Noor Catering"}'
That makes a practice business with its own books: a starter list of accounts, Qatari riyals as its currency, and a financial year starting in January. Keep the id it returns; every other call about this business uses it.
{
"id": "01a1e8c2-…",
"name": "Al Noor Catering",
"base_currency": "QAR",
"livemode": false,
"fiscal_year_start_month": 1,
"timezone": "Asia/Qatar",
"created_at": "2026-11-16T09:12:00Z"
}
How the API works
Amounts
Every amount is a whole number in the smallest unit of the currency. 12.50 QAR is 1250; 99 QAR is 9900. There are no decimals anywhere in the API, so nothing is ever lost to rounding.
Dates
Dates are YYYY-MM-DD, in the business's own time zone. Times are ISO 8601 in UTC.
Errors
A refused request returns a status code and a body like this:
{ "error": { "code": "rejected", "message": "Entry does not balance: debits 2500, credits 100" } }
| 400 | invalid_request: a field is missing or in the wrong format. The message names it. |
| 401 | unauthorised: no key, or a key that's unknown or revoked. |
| 403 | paused: your account is paused; or a feature that's switched off for you. |
| 404 | not_found: it doesn't exist, or it belongs to another partner, or to the other mode (practice or live). |
| 409 | conflict: it already exists, or it has already been done. |
| 422 | rejected: the books refused it, and the message says why (it doesn't balance, the month is closed, the account doesn't exist). |
| 429 | too_many_requests: more than 600 requests in a minute. Wait for the Retry-After seconds and try again. |
Sending the same thing twice
Networks fail. When you record an entry or make a document, send an Idempotency-Key header with a value of your own (your record's id is ideal). If the same key arrives again, BasePipe returns what it made the first time instead of making it twice.
-H "Idempotency-Key: order-58213"
Lists
Lists return { "data": [ … ] }, newest first. Most take ?limit= (50 by default, at most 200).
A first sale, start to finish
Using the business made above. Replace $BIZ with its id.
1. Add a customer
POST /v1/businesses/$BIZ/contacts
{ "name": "Gulf Cafe", "kind": "customer" }
2. Draft an invoice
POST /v1/businesses/$BIZ/documents
{
"kind": "invoice",
"contact_id": "<the customer's id>",
"issue_date": "2026-11-01",
"due_date": "2026-11-30",
"created_by": "user:fatima",
"lines": [
{ "description": "Catering, 40 people", "account": "4000", "quantity": 40, "unit_price": 3500 }
]
}
The draft comes back with its total worked out: 140000 (1,400.00 QAR). Nothing is in the books yet.
3. Approve it
POST /v1/businesses/$BIZ/documents/<id>/approve
{ "approved_by": "owner:fatima" }
Now it's recorded as INV-000001: the customer owes 1,400.00, and sales are 1,400.00 higher.
4. Send it
POST /v1/businesses/$BIZ/documents/<id>/share
Returns a link to a page the customer can open and print, in your brand. Send it however you like, for example on WhatsApp.
5. Record the payment
POST /v1/businesses/$BIZ/payments
{
"direction": "in",
"contact_id": "<the customer's id>",
"date": "2026-11-10",
"amount": 40000,
"money_account": "1010",
"created_by": "user:fatima",
"approved_by": "owner:fatima",
"allocations": [ { "document_id": "<the invoice's id>", "amount": 40000 } ]
}
400.00 arrived in the bank account (1010) against the invoice, which now has 1,000.00 left to pay.
6. See the results
GET /v1/businesses/$BIZ/reports/who-owes-us
GET /v1/businesses/$BIZ/reports/profit-and-loss?from=2026-11-01&to=2026-11-30
GET /v1/businesses/$BIZ/reports/profit-and-loss?from=2026-11-01&to=2026-11-30&format=html&lang=ar
Reports come as JSON, or as a printable page (format=html) in English or Arabic, ready to save as PDF.
Businesses
GET/v1/businesses
Lists every business your partner account owns in the key's mode. A test key sees only practice businesses and a live key only live ones.
Returns
200 with data: a list of businesses, each with id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.
POST/v1/businesses
Creates a business with its own set of books. A test key creates a practice business and a live key a live one. By default it gets the starter chart of accounts (Cash 1000, Bank account 1010, Sales 4000, Rent 6000 and so on).
Body
namestringrequired | The business's name, as it appears on invoices and reports. |
base_currencystring | Three-letter currency code the books are kept in. Defaults to QAR. |
starter_accountsboolean | Add the starter chart of accounts. Defaults to true. Send false to build the chart yourself. |
fiscal_year_start_monthinteger | Month the financial year starts in, from 1 (January) to 12 (December). Defaults to 1. |
timezonestring | IANA time zone used for the business's 'today', reminders and the daily sales question. Defaults to Asia/Qatar. |
Example
{
"name": "Al Noor Catering",
"base_currency": "QAR",
"starter_accounts": true,
"fiscal_year_start_month": 1,
"timezone": "Asia/Qatar"
}
Returns
201 with the business: id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.
Errors
- 400 invalid_request: the body is not a JSON object, name is missing, base_currency is not three capital letters, starter_accounts is not true or false, or fiscal_year_start_month is not a whole number from 1 to 12
- 422 rejected: the time zone is not known (Unknown time zone ...)
GET/v1/businesses/{business}
Returns one of your businesses. Use it to read the base currency, financial year start and time zone before recording anything.
Path
Returns
200 with id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.
Errors
- 404 not_found: no business with this id belongs to your partner account in the key's mode
GET/v1/health
Answers with ok when the API is up and your key is accepted. Like every /v1 route it needs a valid key, so it is a quick way to test a new key.
Returns
200 with {"ok": true}.
Errors
- 401 unauthorised: the Authorization header is missing, is not "Bearer bp_...", or the key is not recognised or has been revoked
- 403 paused: your partner account is paused
- 429 too_many_requests: too many requests from your partner account; wait a minute (see the retry-after header)
Journal entries
GET/v1/businesses/{business}/entries
Lists the business's journal entries, newest number first. To page back, pass next_before from the last page as before.
Path
Query
limitinteger | How many entries to return, 1 to 200. Defaults to 50. |
beforeinteger | Only entries with a number below this one. |
Returns
200 with data (entries in the same shape as Get a journal entry), has_more, and next_before (the number to pass as before for the next page, or null).
Errors
- 400 invalid_request: before is not an entry number
- 404 not_found: the business is not yours or is in the other mode
POST/v1/businesses/{business}/entries
Records a balanced journal entry: total debits must equal total credits, with at least two lines. Saved entries are never edited; to correct one, reverse it. Send an Idempotency-Key header so a retried request returns the entry already recorded instead of a second one.
Path
Body
datedaterequired | Entry date, YYYY-MM-DD. Its month must be open. |
sourcestringrequired | Where the entry comes from: document, manual (an accountant's correction, a bank fee), scheduled (a regular run such as monthly wear and tear) or opening (opening balances). |
source_refstring | Your reference for what the entry came from, such as a document number. Required when source is document. |
memostringrequired | Why the entry was made. |
created_bystringrequired | Who prepared the entry. |
approved_bystringrequired | Who approved the entry. |
linesarrayrequired | At least two lines. |
lines[].accountstringrequired | Account code, e.g. 6300. The account must be in this business's books and switched on. |
lines[].debitinteger | Debit amount in the smallest currency unit (12.50 QAR = 1250). Each line has a debit or a credit above zero, not both. |
lines[].creditinteger | Credit amount in the smallest currency unit. |
lines[].descriptionstring | A note for this line. |
lines[].branchstring | Branch to tag the line with, by id or name. Must exist and be switched on. |
lines[].projectstring | Project to tag the line with, by id or name. Must exist and be switched on. |
Example
{
"date": "2026-11-05",
"source": "manual",
"memo": "QNB monthly account charge",
"created_by": "Fatima Al-Kuwari",
"approved_by": "Fatima Al-Kuwari",
"lines": [
{
"account": "6300",
"debit": 1500,
"description": "Monthly bank charge"
},
{
"account": "1010",
"credit": 1500
}
]
}
Returns
201 with the entry: id, number (runs 1, 2, 3 per business with no gaps), date, source, source_ref, memo, created_by, approved_by, reverses_entry_id, posted_at, and lines (line_no, account, account_name, debit, credit, description). A repeated Idempotency-Key returns the earlier entry.
Errors
- 400 invalid_request: the body is not a JSON object; date is not YYYY-MM-DD; source is not document, manual, scheduled or opening; memo, created_by or approved_by is missing; lines is not a list; a line has no account code; or a debit or credit is not a whole number
- 404 not_found: the business is not yours or is in the other mode
- 422 rejected: fewer than two lines; an account is not in the books or is switched off; a line has both or neither of debit and credit; debits and credits don't balance; the month is closed; a branch or project doesn't exist or is switched off; or source is document with no source_ref
GET/v1/businesses/{business}/entries/{entry}
Returns one journal entry with its lines.
Path
business | The business id. |
entry | The entry id. |
Returns
200 with id, number, date, source (document, manual, scheduled, opening or reversal), source_ref, memo, created_by, approved_by, reverses_entry_id, posted_at, and lines (line_no, account, account_name, debit, credit, description).
Errors
- 404 not_found: the business is not yours, or there is no entry with this id in it
POST/v1/businesses/{business}/entries/{entry}/reverse
Corrects a saved entry by recording its mirror image: every debit becomes a credit and the other way round. The original stays as it was. If the original's month is closed, pass a date in an open month.
Path
business | The business id. |
entry | The id of the entry to reverse. |
Body
reasonstringrequired | Why it is reversed. The memo becomes 'Reversal of entry <number>: <reason>'. |
bystringrequired | Who reversed it (recorded as both preparer and approver). |
datedate | Date of the reversal, YYYY-MM-DD. Defaults to the original entry's date. |
Example
{
"reason": "Bank charge was posted twice",
"by": "Fatima Al-Kuwari",
"date": "2026-11-10"
}
Returns
201 with the new reversal entry: source reversal, reverses_entry_id set to the original's id, and its lines.
Errors
- 400 invalid_request: the body is not a JSON object, reason or by is missing, or date is not YYYY-MM-DD
- 404 not_found: the business is not yours, or there is no entry with this id in it
- 422 rejected: the entry is itself a reversal, it has already been reversed, or the reversal's month is closed
POST/v1/businesses/{business}/months/{month}/close
Closes a month so nothing more can be recorded in it, for example after the accountant has checked it. Closing a month that is already closed changes nothing.
Path
business | The business id. |
month | The month, YYYY-MM, e.g. 2026-10. |
Body
bystringrequired | Who closed the month. |
Example
{
"by": "Fatima Al-Kuwari"
}
Returns
200 with month and status (closed).
Errors
- 400 invalid_request: the month doesn't look like 2026-10, the body is not a JSON object, or by is missing
- 404 not_found: the business is not yours or is in the other mode
GET/v1/businesses/{business}/reports/trial-balance
Totals every account's debits and credits up to and including a date. Only accounts with activity are listed; total_debit always equals total_credit.
Path
Query
as_ofdate | Last day to include, YYYY-MM-DD. Defaults to today (UTC). |
Returns
200 with as_of, currency, accounts (code, name, type, debit, credit, balance; balance is debit minus credit for asset and expense accounts and credit minus debit for the rest), total_debit, total_credit.
Errors
- 400 invalid_request: as_of is not YYYY-MM-DD
- 404 not_found: the business is not yours or is in the other mode
POST/v1/businesses/{business}/transfers
Records money moved between the business's own bank, cash and card accounts, for example cash taken from the till to the bank. It is saved as a manual journal entry debiting the receiving account and crediting the sending one. Send an Idempotency-Key header to make retries safe.
Path
Body
datedaterequired | Transfer date, YYYY-MM-DD. Its month must be open. |
from_accountstringrequired | Code of the account the money leaves. |
to_accountstringrequired | Code of the account the money goes into. |
amountintegerrequired | Amount above zero in the smallest currency unit (12.50 QAR = 1250). |
memostring | Why. Defaults to 'Transfer from <account> to <account>'. |
created_bystringrequired | Who prepared it. |
approved_bystringrequired | Who approved it. |
Example
{
"date": "2026-11-06",
"from_account": "1000",
"to_account": "1010",
"amount": 850000,
"memo": "Till cash deposited at QNB",
"created_by": "Fatima Al-Kuwari",
"approved_by": "Fatima Al-Kuwari"
}
Returns
201 with the journal entry, in the same shape as Record a journal entry (source manual, source_ref transfer).
Errors
- 400 invalid_request: date is not YYYY-MM-DD; from_account, to_account, created_by or approved_by is missing; or amount is not a whole number above zero
- 404 not_found: the business is not yours or is in the other mode
- 422 rejected: an account is not in the books or is switched off; both accounts are the same; an account is not an asset or liability (bank, cash or card); both are liabilities; or the month is closed
Customers and suppliers
GET/v1/businesses/{business}/contacts
Lists the business's contacts in name order. Filter by kind to get only customers or only suppliers; contacts of kind both are included in either filter.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Query
kindstring | customer, supplier or both. customer or supplier also returns contacts of kind both. |
Returns
200 with data: a list of contacts, each with id, kind, name, name_ar, phone, email, tax_number, address, country, is_resident, default_tax, created_at.
Errors
- 400 invalid_request: kind is not customer, supplier or both.
- 404 not_found: the business does not exist or is not visible to this key.
POST/v1/businesses/{business}/contacts
Adds a customer, a supplier, or a contact that is both to the business's books. Invoices, bills and credits must name a contact; expenses and cash sales may. A supplier based outside Qatar (is_resident false) gets the 5% withholding tax code WHT5 as its default tax unless you send default_tax yourself.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
kindstringrequired | customer, supplier or both. A customer can be used on invoices, cash sales and credit notes; a supplier on bills, expenses and supplier credits; both on either side. |
namestringrequired | The contact's name as it should appear on documents. |
name_arstring | The name in Arabic. Shown under the English name on shared invoices and matched when owners write in Arabic. |
phonestring | Phone number, free text. |
emailstring | Email address, free text. |
tax_numberstring | The contact's tax registration number. Printed on shared invoices. |
addressstring | Postal address, free text. Printed on shared invoices. |
countrystring | Two-letter country code such as QA or AE. Stored in capitals. |
is_residentboolean | Whether the contact is resident in Qatar. Defaults to true. false on a supplier (or both) with no default_tax sets up and uses WHT5. |
default_taxstring | Code of a tax code already set up for the business. Used on every document line for this contact that leaves out "tax". Send null for no default. |
Example
{
"kind": "supplier",
"name": "Doha Flour Mill",
"name_ar": "مطحنة الدوحة للدقيق",
"phone": "+974 4444 1234",
"email": "accounts@dohaflourmill.qa",
"tax_number": "QA300123456",
"address": "Street 24, Industrial Area, Doha",
"country": "QA",
"is_resident": true
}
Returns
201 with the contact: id, kind, name, name_ar, phone, email, tax_number, address, country, is_resident, default_tax (tax code or null), created_at.
Errors
- 400 invalid_request: kind is not customer, supplier or both; name is missing; a text field is not text; country is not two letters; is_resident is not true or false.
- 400 invalid_request: the default_tax code is not set up for this business; nothing is saved.
- 404 not_found: the business does not exist or is not visible to this key.
Documents
GET/v1/businesses/{business}/documents
Lists the business's documents, newest issue date first. Filter by kind and status, for example status=draft to find drafts waiting for approval.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Query
kindstring | invoice, bill, expense, cash_sale, credit_note or supplier_credit. |
statusstring | draft (not in the books yet), recorded (approved and in the books) or void (cancelled; its entry was reversed). |
limitinteger | How many to return, 1 to 200. Defaults to 50. |
Returns
200 with data: a list of documents in the same shape as the create response, including lines and credits.
Errors
- 400 invalid_request: kind or status is not one of the allowed values.
- 404 not_found: the business does not exist or is not visible to this key.
POST/v1/businesses/{business}/documents
Creates a draft invoice, bill, expense, cash sale, credit note or supplier credit. A draft is not in the books and has no number; approve it to record it. Invoices and bills are settled later by payments; expenses and cash sales were paid on the spot and name the money account used; credit notes and supplier credits reverse sales or purchases and are applied to invoices or bills, or refunded.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
kindstringrequired | invoice (a sale the customer pays later), bill (a purchase you pay later), expense (a purchase already paid), cash_sale (a sale paid on the spot), credit_note (takes a sale back and lowers what a customer owes), or supplier_credit (takes a purchase back and lowers what you owe a supplier). The kind cannot be changed later. |
contact_idstring | Id of a contact. Required for invoice, bill, credit_note and supplier_credit; optional for expense and cash_sale. Sales kinds (invoice, cash_sale, credit_note) need a customer or both; purchase kinds (bill, expense, supplier_credit) need a supplier or both. |
issue_datedaterequired | The document's date, YYYY-MM-DD. The entry is recorded on this date when approved, so its month must be open by then. |
due_datedate | When an invoice or bill must be paid, YYYY-MM-DD. Defaults to issue_date (due on receipt). Ignored for other kinds, whose due date is always the issue date. |
referencestring | Your own reference, such as the supplier's invoice number or a purchase order number. |
memostring | A note on the document. |
created_bystringrequired | Who prepared the draft, such as a user's email or name. Kept on the document and its entry. |
money_accountstring | Expense and cash_sale only: code of the account the money was paid from or into, such as 1000 (Cash) or 1010 (Bank account). Must be an asset account; for an expense it can also be an equity account such as 3000 when the owner paid personally. Can be left out on the draft but is needed before approval. Must be left out for invoice, bill, credit_note and supplier_credit. |
party_namestring | The other party's name when there is no contact, such as the shop on a receipt. Used in the entry's description and in duplicate checks. |
attachment_refstring | A reference to a stored file for this document. Set by the receipts endpoint; usually left out. |
confidencenumber | From 0 to 1: how sure whoever prepared the draft (for example an AI reader) was that it is right. Informational only. |
currencystring | Three-letter currency code of the document, such as USD or AED. Defaults to the business's currency. Line amounts are in this currency's smallest unit. |
ratenumber | For a document in another currency: how many units of the business's currency one unit of this currency is worth on the issue date (for example 3.64 for USD to QAR). If left out it is looked up from your exchange rates and BasePipe's fixed pegs; a document with no rate can be saved but not approved. |
branchstring | Name or id of a branch tag for the whole document. Lines without their own branch use it. |
projectstring | Name or id of a project tag for the whole document. Lines without their own project use it. |
linesarrayrequired | At least one line. The document total is the sum of each line's amount plus its tax (withholding tax is subtracted instead). |
lines[].descriptionstring | What the line is for. Required unless the line names an item, in which case it defaults to the item's name. |
lines[].accountstring | Code of the account the line goes to, such as 4000 (Sales) or 6000 (Rent). Each line needs account or item. With an item on a sales document it defaults to the item's sales account and must be an income account; on a purchase document the line always goes to the item's stock account, and any account given must be that one. |
lines[].itemstring | Code of a stock item. Approving the document moves stock: bills and expenses bring it in at the line amount, invoices and cash sales take it out at average cost, credit notes bring returns back in, supplier credits send it back out. |
lines[].quantitynumber | How many, above zero. Defaults to 1. Can have decimals, such as 2.5 kg. |
lines[].unit_priceintegerrequired | Price of one unit before discount and tax, in the smallest unit of the document's currency (12.50 QAR is 1250). Must be above zero. |
lines[].discountinteger | An amount taken off the line, in the smallest currency unit. 0 means no discount. Must be less than quantity x unit_price. Give discount or discount_percent, not both. |
lines[].discount_percentnumber | A percentage taken off quantity x unit_price, from 0 up to but not including 100; the result is rounded to the nearest unit. Give discount or discount_percent, not both. |
lines[].taxstring | Code of a tax code set up for the business. Leave the field out to use the contact's default tax code; send null for no tax. Output (sales) codes only go on invoices, cash sales and credit notes; input and withholding codes only on bills, expenses and supplier credits. Tax is the line amount (after discount) x the code's rate, rounded. |
lines[].branchstring | Name or id of a branch tag for this line only. |
lines[].projectstring | Name or id of a project tag for this line only. |
Example
{
"kind": "invoice",
"contact_id": "01936f4e-8a2b-7c3d-9e4f-5a6b7c8d9e0f",
"issue_date": "2026-11-16",
"due_date": "2026-12-16",
"reference": "PO-4471",
"memo": "Catering for the National Day staff lunch",
"created_by": "fatima@gulfcafe.qa",
"lines": [
{
"description": "Lunch buffet, per person",
"account": "4000",
"quantity": 40,
"unit_price": 6500,
"discount_percent": 10
},
{
"description": "Delivery and setup",
"account": "4100",
"quantity": 1,
"unit_price": 25000,
"tax": null
}
]
}
Returns
201 with the draft document: id, kind, status (draft), number (null until approved), contact {id, name}, party_name, money_account, attachment_ref, confidence, currency, rate, base_total (null until approved), issue_date, due_date, reference, memo, total, paid, outstanding, created_by, created_at, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, branch, project, order_id, recurring_id, lines [{line_no, description, account, item, quantity, unit_price, discount, amount (quantity x unit_price less discount), tax, tax_amount}], credits.
Errors
- 400 invalid_request: the body is not a JSON object; kind is not one of the six kinds; issue_date or due_date is not YYYY-MM-DD; created_by is missing; contact_id is not an id; currency is not three letters; rate is not above zero; confidence is not from 0 to 1.
- 400 invalid_request: lines is empty; a line has neither account nor item; a line has no description and no item; quantity is not above zero; unit_price or discount is not a whole number above zero; both discount and discount_percent are given; discount_percent is not from 0 up to 100.
- 404 not_found: the business does not exist or is not visible to this key.
- 422 rejected: an invoice, bill or credit has no contact; the contact is not in this business, or is a supplier on a sale or a customer on a purchase.
- 422 rejected: a money_account is given on an invoice, bill or credit; the money account is not in the books or is not a bank, cash (or, for an expense, owner's) account.
- 422 rejected: a line's account, item, tax code, branch or project is not in the business or is switched off; an item sold goes to a non-income account; a purchase line with an item names an account other than the item's stock account; a tax code is on the wrong side (sales vs purchases); a discount takes the whole line.
- 422 rejected: the currency is not one BasePipe knows; the business is read-only because its plan is unpaid.
GET/v1/businesses/{business}/documents/{document}
Returns one document with its lines, what has been paid or credited against it, and any documents that look like duplicates. Check possible_duplicates before approving a draft made from a receipt.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the document. |
Returns
200 with the document (same fields as the create response) plus possible_duplicates: other non-void documents of the same kind with the same total, dated within 3 days, with the same contact or party name, each with document_id, number, status, issue_date, party, total. credits lists credit applications touching this document: id, credit_id, document_id, credit_number, document_number, date, amount.
Errors
- 404 not_found: the business or the document does not exist or is not visible to this key.
PUT/v1/businesses/{business}/documents/{document}
Replaces a draft's details and all of its lines. Send the whole draft again: fields left out are cleared (contact_id, due_date, reference, memo, money_account, party_name, attachment_ref and confidence), except currency and rate, which keep their current values. The kind, created_by, branch and project cannot be changed here; recorded and void documents cannot be changed at all.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the draft document. |
Body
contact_idstring | Id of a contact. Required for invoice, bill, credit_note and supplier_credit; must be a customer (or both) on sales kinds and a supplier (or both) on purchase kinds. |
issue_datedaterequired | The document's date, YYYY-MM-DD. |
due_datedate | Invoices and bills only: when payment is due, YYYY-MM-DD. Defaults to issue_date. |
referencestring | Your own reference, such as the supplier's invoice number. |
memostring | A note on the document. |
money_accountstring | Expense and cash_sale only: code of the bank or cash account paid from or into (or an equity account for an expense the owner paid personally). Must be left out for invoices, bills and credits. |
party_namestring | The other party's name when there is no contact. |
attachment_refstring | Reference to the stored receipt file. Send back the value from the document to keep the receipt attached. |
confidencenumber | From 0 to 1: how sure the preparer was. Informational only. |
currencystring | Three-letter currency code. Left out, the draft keeps its currency. |
ratenumber | Units of the business's currency per one unit of the document's currency. Left out, the current rate is kept if the currency is unchanged, otherwise it is looked up. |
linesarrayrequired | The full list of lines, replacing the old ones. At least one. |
lines[].descriptionstring | What the line is for. Required unless the line names an item. |
lines[].accountstring | Account code for the line. Each line needs account or item; see the create endpoint for how items choose accounts. |
lines[].itemstring | Code of a stock item. |
lines[].quantitynumber | How many, above zero. Defaults to 1. Decimals allowed. |
lines[].unit_priceintegerrequired | Price of one unit before discount and tax, in the smallest currency unit. Above zero. |
lines[].discountinteger | Amount off the line in the smallest currency unit, less than quantity x unit_price. Not with discount_percent. |
lines[].discount_percentnumber | Percentage off quantity x unit_price, from 0 up to but not including 100. Not with discount. |
lines[].taxstring | Tax code for the line. Leave it out to use the contact's default; null for no tax. |
lines[].branchstring | Name or id of a branch tag for this line. |
lines[].projectstring | Name or id of a project tag for this line. |
Example
{
"contact_id": "01936f4e-9b1c-7d2e-8f3a-4b5c6d7e8f90",
"issue_date": "2026-11-14",
"due_date": "2026-12-14",
"reference": "DFM-20931",
"memo": "Flour delivery for November",
"lines": [
{
"description": "Flour, 50 kg bag",
"account": "5000",
"quantity": 20,
"unit_price": 9500,
"discount": 5000
},
{
"description": "Delivery to Al Sadd branch",
"account": "6500",
"quantity": 1,
"unit_price": 15000
}
]
}
Returns
200 with the updated draft document, same shape as the create response.
Errors
- 400 invalid_request: the same validation errors as creating a draft (dates, lines, amounts, discount, currency, rate, confidence).
- 404 not_found: the business or the document does not exist or is not visible to this key.
- 422 rejected: the document is recorded or void and can no longer be changed.
- 422 rejected: the same book rules as creating a draft (contact kind, money account, accounts, items, tax codes, tags, discounts, currency).
DELETE/v1/businesses/{business}/documents/{document}
Deletes a draft and its lines for good. Only drafts can be deleted; to cancel a recorded document, void it instead.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the draft document. |
Returns
200 with id and deleted: true.
Errors
- 404 not_found: the business or the document does not exist or is not visible to this key.
- 422 rejected: the document is recorded or void; recorded documents are never deleted.
POST/v1/businesses/{business}/documents/{document}/approve
Records a draft in the books. The document gets its number (INV-, BILL-, EXP-, SALE-, CN- or SC- followed by six digits) and its journal entry, dated on the issue date, and stock items move. After this it cannot be changed, only voided.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the draft document. |
Body
approved_bystringrequired | Who approved it, such as the owner's or accountant's email. Kept on the document and its entry. |
Example
{
"approved_by": "owner@gulfcafe.qa"
}
Returns
200 with the document, now with status recorded, number, approved_by, recorded_at, entry_id and base_total (the total in the business's currency). For an invoice, bill or credit, outstanding is the full total; for an expense or cash sale, paid is the full total.
Errors
- 400 invalid_request: approved_by is missing.
- 404 not_found: the business or the document does not exist or is not visible to this key.
- 422 rejected: the document is already recorded or void.
- 422 rejected: an expense or cash sale has no money_account yet.
- 422 rejected: the document is in another currency and has no exchange rate.
- 422 rejected: after withholding tax nothing is left to pay.
- 422 rejected: the business has no receivable or payable account set; the month of the issue date is closed; not enough of a stock item is in stock; the business is read-only because its plan is unpaid.
POST/v1/businesses/{business}/documents/{document}/void
Cancels a recorded document by reversing its entry and any stock it moved. The document stays in the books with status void. Void the payments and take off the credits set against it first.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the recorded document. |
Body
reasonstringrequired | Why it is being voided. Kept on the document and in the reversing entry's description. |
bystringrequired | Who voided it. |
datedate | Date of the reversing entry, YYYY-MM-DD. Defaults to the original entry's date; give a date in an open month if that month is closed. |
Example
{
"reason": "Issued to the wrong customer",
"by": "owner@gulfcafe.qa",
"date": "2026-11-16"
}
Returns
200 with the document, now with status void, voided_by, voided_at and void_reason.
Errors
- 400 invalid_request: reason or by is missing; date is not YYYY-MM-DD.
- 404 not_found: the business or the document does not exist or is not visible to this key.
- 422 rejected: the document is a draft (delete it instead) or is already void.
- 422 rejected: payments are allocated to it, or credits are applied to or from it.
- 422 rejected: the month of the reversal date is closed; the stock it moved has moved since and can't be undone at its original cost; the business is read-only.
Payments
GET/v1/businesses/{business}/payments
Lists the business's payments in and out, newest first, with what each was allocated to.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Query
limitinteger | How many to return, 1 to 200. Defaults to 50. |
Returns
200 with data: a list of payments in the same shape as the record response, including void payments.
Errors
- 404 not_found: the business does not exist or is not visible to this key.
POST/v1/businesses/{business}/payments
Records money received from a customer or paid to a supplier, straight into the books, and optionally sets it against open documents. Money in settles invoices and supplier credit refunds; money out settles bills and credit note refunds. Any part not allocated stays with the contact as a deposit you can allocate later.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
directionstringrequired | in for money received, out for money paid. |
contact_idstringrequired | Id of the customer or supplier. A contact of kind both is treated as a customer for money in and a supplier for money out, unless the allocations point at its invoices or credit notes. |
datedaterequired | The date the money moved, YYYY-MM-DD. Its month must be open. |
amountintegerrequired | The amount that reached or left the account, in the smallest unit of the business's currency. Above zero. |
money_accountstringrequired | Code of the bank or cash account, such as 1010 (Bank account) or 1000 (Cash). Must be an active asset account. |
referencestring | A bank or cheque reference. |
memostring | Description of the entry. Defaults to text like 'Payment from Gulf Cafe' or 'Refund to Gulf Cafe'. |
created_bystringrequired | Who entered the payment. |
approved_bystringrequired | Who approved it. Payments are recorded at once, so this is required. |
allocationsarray | Recorded documents of this contact to set the payment against. The total allocated, in the business's currency, cannot exceed amount. |
allocations[].document_idstringrequired | Id of a recorded invoice, bill, credit note or supplier credit of the same contact. |
allocations[].amountintegerrequired | How much of the document this settles, in the smallest unit of the document's currency. Cannot exceed what is still outstanding on it. |
allocations[].base_amountinteger | For a document in another currency: what this part was worth in the business's currency. Defaults to amount converted at the document's rate. A difference from the document's rate is recorded as an exchange gain or loss on account 6950. |
Example
{
"direction": "in",
"contact_id": "01936f4e-8a2b-7c3d-9e4f-5a6b7c8d9e0f",
"date": "2026-11-20",
"amount": 259000,
"money_account": "1010",
"reference": "QNB TRF 88213",
"created_by": "fatima@gulfcafe.qa",
"approved_by": "owner@gulfcafe.qa",
"allocations": [
{
"document_id": "01937a10-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
"amount": 259000
}
]
}
Returns
201 with the payment: id, direction, status (recorded), contact {id, name}, date, amount, money_account, reference, memo, created_by, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, allocations [{document_id, number, amount}]. Send an Idempotency-Key header to make retries safe: a repeat with the same key returns the payment already recorded.
Errors
- 400 invalid_request: direction is not in or out; contact_id or an allocation's document_id is not an id; date is not YYYY-MM-DD; amount, an allocation amount or base_amount is not a whole number above zero; money_account, created_by or approved_by is missing; allocations is not a list.
- 404 not_found: the business does not exist or is not visible to this key.
- 422 rejected: the contact is not in this business; the money account is not an active bank or cash account; the business has no receivable or payable account set.
- 422 rejected: an allocated document is not in this business, is not recorded, belongs to another contact, was paid on the spot (expense or cash sale), or is on the wrong side for the direction.
- 422 rejected: an allocation is more than the document has left to pay or refund, or the allocations add up to more than the payment.
- 422 rejected: the month is closed; the business is read-only.
GET/v1/businesses/{business}/payments/{payment}
Returns one payment with its current allocations. Allocations taken off when the payment was voided are not listed.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
payment | Id of the payment. |
Returns
200 with the payment: id, direction, status, contact, date, amount, money_account, reference, memo, created_by, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, allocations [{document_id, number, amount}].
Errors
- 404 not_found: the business or the payment does not exist or is not visible to this key.
POST/v1/businesses/{business}/payments/{payment}/allocations
Sets part of an existing payment against one recorded document of the same contact, for example a customer's deposit against their next invoice. Use it for money that was not allocated when the payment was recorded.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
payment | Id of the payment. |
Body
document_idstringrequired | Id of a recorded invoice, bill, credit note or supplier credit of the payment's contact, on the right side for the payment's direction. |
amountintegerrequired | How much of the document this settles, in the smallest unit of the document's currency. Cannot exceed what is outstanding on it. |
bystringrequired | Who made the allocation. |
base_amountinteger | For a document in another currency: what this part was worth in the business's currency. Defaults to amount at the document's rate; the difference is recorded as an exchange gain or loss. |
Example
{
"document_id": "01937a10-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
"amount": 50000,
"by": "fatima@gulfcafe.qa"
}
Returns
201 with the payment, its allocations list now including the new one.
Errors
- 400 invalid_request: document_id is not an id; amount or base_amount is not a whole number above zero; by is missing.
- 404 not_found: the business or the payment does not exist or is not visible to this key.
- 422 rejected: the payment is void.
- 422 rejected: the document is not in this business, is not recorded, belongs to another contact, was paid on the spot, or is on the wrong side for the direction.
- 422 rejected: the amount is more than the document has left, or more than the payment has left to allocate; the month of the payment is closed when an exchange difference has to be recorded.
POST/v1/businesses/{business}/payments/{payment}/void
Cancels a payment by reversing its entry, and any exchange difference entries, and takes off all its allocations, so the documents it paid are open again. The payment stays with status void.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
payment | Id of the payment. |
Body
reasonstringrequired | Why it is being voided, such as a bounced cheque. |
bystringrequired | Who voided it. |
datedate | Date of the reversing entry, YYYY-MM-DD. Defaults to the payment's date; give a date in an open month if that month is closed. |
Example
{
"reason": "Cheque returned unpaid by the bank",
"by": "owner@gulfcafe.qa"
}
Returns
200 with the payment, now with status void, voided_by, voided_at, void_reason and an empty allocations list.
Errors
- 400 invalid_request: reason or by is missing; date is not YYYY-MM-DD.
- 404 not_found: the business or the payment does not exist or is not visible to this key.
- 422 rejected: the payment is already void; the month of the reversal date is closed; the business is read-only.
Receipts
GET/v1/businesses/{business}/documents/{document}/file
Returns the original receipt photo or PDF stored for a document, for the owner or an accountant to look at. The response is the file itself with its content type, not JSON.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
document | Id of the document the receipt belongs to. |
Returns
200 with the file bytes, Content-Type set to the file's media type (such as image/jpeg or application/pdf) and Cache-Control private, max-age=300.
Errors
- 404 not_found: the business or the document does not exist or is not visible to this key.
- 404 not_found: the document has no stored file, file storage is off, or the file is missing (Receipt file not found).
POST/v1/businesses/{business}/receipts
Upload a receipt photo or PDF; it is stored (when file storage is on) and read by AI into a draft expense with an account for each line, checked against the printed total, plus plain questions for the owner. Send JSON {"file": base64, "media_type": "image/jpeg"} or a multipart form with a "file" field; media types are image/jpeg, image/png, image/webp, image/gif and application/pdf, up to 10 MB. Optional text fields created_by (defaults to claude-assistant) and money_account (defaults to 1000 for cash, 1010 for card or bank transfer, none if unknown) can be sent alongside; nothing is recorded until the draft is approved.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
filestringrequired | The receipt: base64 in a JSON body (a data: URL prefix is allowed), or a file part in a multipart form. |
media_typestringrequired | JSON body only: image/jpeg, image/png, image/webp, image/gif or application/pdf. In a form, the file part's own type is used. |
created_bystring | Who sent the receipt. Defaults to claude-assistant. |
money_accountstring | Code of the account it was paid from, overriding what the reader saw on the receipt. |
Returns
201 with kind receipt, reading {supplier, date, currency, printed_total, lines_total, lines_add_up, paid_with, confidence}, questions (list of text), stored (whether the file was kept) and draft (the draft expense, as in the documents endpoints, with possible_duplicates). If the file is a till report: 200 with kind till_report, till {date, cash, card, total, printed_total, adds_up, confidence, questions} and stored, and nothing is created. If it is a bank statement: 201 with kind bank_statement and stored; send it to the statements endpoint instead.
Errors
- 400 invalid_request: no file; the JSON has no media_type or the file is not valid base64; the media type is not allowed; the file is empty or over 10 MB.
- 403 read_only: the business is read-only until its plan is paid.
- 404 not_found: the business does not exist or is not visible to this key.
- 422 unreadable: the reader could not read the file, or no amounts could be read.
- 422 not_a_receipt: the file doesn't look like a receipt or bill.
- 422 rejected: the draft could not be created under the books' rules, for example an unknown currency or money account.
- 429 receipt_limit: this month's receipt reading on the business's plan is used up.
- 502 reader_unavailable: the reading service is not answering; try again.
- 503 reader_off: receipt reading is not switched on for this service.
Bank
GET/v1/businesses/{business}/bank-lines
Lists imported bank lines, newest first. Filter by status to find the lines that still need matching.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
statusstring | unmatched, matched or ignored. |
accountstring | Only lines on this bank or cash account code. |
limitinteger | How many lines, 1 to 500. Defaults to 100. |
Returns
200 with data: a list of bank lines, each with id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "status" is not unmatched, matched or ignored
GET/v1/businesses/{business}/bank-lines/{line}
Returns one bank line. While it is unmatched, it also lists lines in the books it could be (same account, same amount, not matched yet, within seven days, closest date first) and the accounts it most likely belongs to, from the owner's rules first and then from how similar lines were recorded before.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
line | The bank line id. |
Returns
200 with id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at, plus possible_matches [{journal_line_id, entry_id, entry_number, entry_date, memo, days_apart}] (up to 10) and suggested_accounts [{account, account_name, source (rule or past entries), rule_id, confidence (0 to 1)}] (up to 3). Both lists are empty unless the line is unmatched.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the bank line is not in this business
POST/v1/businesses/{business}/bank-lines/{line}/ignore
Marks an unmatched bank line as one that should never be matched, such as a duplicate the bank later corrected. Set-aside lines are counted separately in the bank reconciliation report.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
line | The bank line id. |
Body
reasonstringrequired | Why the line is set aside. |
bystringrequired | Who set it aside. |
Example
{
"reason": "Duplicate of the 3 November transfer; QNB reversed it the next day",
"by": "Fatima Al-Kuwari"
}
Returns
200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now ignored, with ignored_reason.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the bank line is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "reason" or "by" is missing
- 422 rejected when the bank line is not unmatched
POST/v1/businesses/{business}/bank-lines/{line}/match
Links an unmatched bank line to the line in the books for the same money, such as a payment already recorded. Matching never changes the books and can be undone. Take the journal_line_id from the bank line's possible_matches.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
line | The bank line id. |
Body
journal_line_idstringrequired | Id of the journal line on the same bank account, with exactly the same amount. |
bystringrequired | Who confirmed the match. |
Example
{
"journal_line_id": "01934f6e-2b7a-7c41-9d3e-5a8f0c2e7b19",
"by": "Fatima Al-Kuwari"
}
Returns
200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now matched.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the bank line is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "journal_line_id" is not an id or "by" is missing
- 422 rejected when the bank line is already matched or set aside
- 422 rejected when the journal line is not in this business's books or its entry was reversed, is on a different account, has a different amount, or is already matched to another bank line
POST/v1/businesses/{business}/bank-lines/{line}/record
For a bank line with nothing behind it in the books, such as a bank fee, records an entry between the bank account and the account you name, dated the bank line's date, and matches the line to it. Money in is credited to that account; money out is debited to it.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
line | The bank line id. |
Body
accountstringrequired | Code of the account the money was for, for example 6300 for bank fees. Not the bank account itself. |
memostring | Reason for the entry. Defaults to the bank line's description. |
created_bystringrequired | Who prepared the entry. |
approved_bystringrequired | Who approved the entry. Also saved as who matched the line. |
Example
{
"account": "6300",
"memo": "QNB monthly account fee",
"created_by": "Fatima Al-Kuwari",
"approved_by": "Khalid Al-Thani"
}
Returns
201 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now matched to the new entry (matched_entry_number).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the bank line is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "account", "created_by" or "approved_by" is missing
- 422 rejected when the account is not a switched-on account of this business, or is the bank account itself
- 422 rejected when the bank line is already matched or set aside
- 422 rejected when the bank line's month is closed
POST/v1/businesses/{business}/bank-lines/{line}/unmatch
Puts a matched or set-aside bank line back to unmatched and removes its match. An entry that was recorded from the bank line stays in the books; reverse it separately if it was wrong.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
line | The bank line id. |
Body
bystringrequired | Who undid it. |
Example
{
"by": "Fatima Al-Kuwari"
}
Returns
200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now unmatched.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the bank line is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "by" is missing
POST/v1/businesses/{business}/bank-lines/import
Adds lines from a bank statement to one of the business's bank or cash accounts. Importing the same statement again adds nothing twice: a line is recognised by the bank's own id, or by its date, amount, description, reference and position when there is no id.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
accountstringrequired | Code of the bank or cash account (an asset account that is switched on), for example 1010. |
bystringrequired | Who imported the statement. |
linesarrayrequired | The statement lines, 1 to 2,000 at a time. |
lines[].datedaterequired | Date the bank shows for the line. |
lines[].amountintegerrequired | Amount in the smallest currency unit, not zero: above zero for money in, below zero for money out. |
lines[].descriptionstring | The bank's wording. Stored as "(no description)" when left out. |
lines[].referencestring | The bank's reference for the line. |
lines[].balanceinteger | The statement's running balance after this line. The latest one is used as the statement balance in the bank reconciliation report. |
lines[].idstring | The bank's own id for the line, if it gives one. Used to skip lines already imported. |
Example
{
"account": "1010",
"by": "Fatima Al-Kuwari",
"lines": [
{
"date": "2026-11-02",
"amount": 525000,
"description": "TRANSFER FROM AL MEERA TRADING",
"reference": "FT2611020045",
"balance": 4997500,
"id": "QNB-88213401"
},
{
"date": "2026-11-03",
"amount": -38500,
"description": "KAHRAMAA BILL PAYMENT 40123456",
"balance": 4959000,
"id": "QNB-88213422"
},
{
"date": "2026-11-03",
"amount": -2500,
"description": "BANK CHARGES",
"balance": 4956500,
"id": "QNB-88213423"
}
]
}
Returns
201 with received (lines sent), added (new lines saved) and already_imported (lines skipped because they were imported before).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "lines" is missing, empty or longer than 2,000
- 400 invalid_request when a line's "amount" is not a whole number or is zero, its "balance" is not a whole number, or its "date" is not a date
- 400 invalid_request when "account" or "by" is missing
- 422 rejected when "account" is not a switched-on asset account of this business
GET/v1/businesses/{business}/reports/bank-reconciliation
For one bank or cash account up to a date, shows the balance in the books, what is on the statement but not matched in the books, and what is in the books but not matched to a statement line. The expected statement balance is the books balance plus the unmatched bank lines less the unmatched book lines.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
accountstring | Bank or cash account code. Defaults to 1010. |
as_ofdate | Up to and including this date. Defaults to today (UTC). |
Returns
200 with account, as_of, currency, books_balance, on_statement_not_in_books {count, total}, in_books_not_on_statement {count, total}, set_aside (count of ignored lines), expected_statement_balance, statement_balance (the latest running balance imported on or before as_of, or null) and difference (statement_balance less expected_statement_balance, or null).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "as_of" is not a date like 2026-11-05
Bank statements
POST/v1/businesses/{business}/bank-lines/card-payouts
Records the chosen bank lines as card machine payouts, clearing them against account 1150 (Card payments on the way), where the day's card sales went. Use the ids in card_payouts from a statement import once the owner confirms them. Lines that are already matched or are money out are skipped.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
line_idsarrayrequired | Ids of the bank lines to record as payouts. |
approved_bystring | Who approved recording them. Defaults to api. |
Example
{
"line_ids": [
"01938b22-4d5e-7f60-8172-93a4b5c6d7e8",
"01938b22-4d5e-7f60-8172-93a4b5c6d7e9"
],
"approved_by": "owner@gulfcafe.qa"
}
Returns
200 with recorded: how many lines were recorded.
Errors
- 400 invalid_request: line_ids is missing or is not a list of text.
- 400 invalid_request: an id in line_ids is not a valid id (A value had the wrong format).
- 404 not_found: the business does not exist or is not visible to this key.
- 422 rejected: a line's month is closed; the business is read-only.
POST/v1/businesses/{business}/statements
Upload a bank statement as JSON {"file": base64, "media_type": ...}: a CSV export (text/csv, text/comma-separated-values, application/csv or text/plain) is read directly; a PDF or a photo of a page (application/pdf, image/jpeg, image/png, image/webp, image/gif) is read by AI. Up to 20 MB; Excel files are refused. The lines are checked against the statement's own opening, closing and running balances, imported onto the bank account (sending the same statement twice adds nothing), matched where there is exactly one possible match in the books, and passed through the business's auto-recording rules; card machine payouts are picked out for the owner to clear.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Body
filestringrequired | The statement file, base64-encoded. A data: URL prefix is allowed. |
media_typestringrequired | The file's media type, from the lists in the description. |
accountstring | Code of the bank account the statement belongs to, such as 1010. Needed when the business has more than one bank account and the bank's name doesn't pick one out. |
imported_bystring | Who imported it. Defaults to api. |
Returns
201 with account, bank_name, from, to (the statement period), lines (lines read), added (new lines imported), matched (lines matched automatically), recorded_by_rules, card_payouts [{id, amount, date, description}] (unmatched money in that looks like card machine payouts), still_open (other unmatched lines left for review) and adds_up (true when the balances were checked and agree, null when the statement prints none).
Errors
- 400 invalid_request: the body is not JSON; file or media_type is missing; the file is an Excel file; file is not valid base64; the file is empty or over 20 MB.
- 400 invalid_request: no account was given and one couldn't be chosen; the account is not one of the business's bank or cash accounts.
- 404 not_found: the business does not exist or is not visible to this key.
- 422 unreadable: a CSV's columns weren't recognised and AI reading is off, or the reader could not read the file.
- 422 not_a_statement: the file doesn't look like a bank statement.
- 422 does_not_add_up: the lines don't follow the statement's running balances or don't add up from opening to closing balance; nothing was imported.
- 502 reader_unavailable: the reading service is not answering; try again.
- 503 reader_off: statement reading for PDFs and images is not switched on for this service.
- 400 invalid_request: the business has no bank account to import into.
Coding rules
GET/v1/businesses/{business}/rules
Lists every rule, switched on or off, in the order they are tried: lowest priority number first, then oldest.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of rules, each with id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/rules
Saves an owner-approved rule that says what a recurring bank line is, for example any line containing "KAHRAMAA" is the electricity and water bill. A rule only suggests the account unless auto_record is true, in which case running the rules records matching lines on their own. When several rules fit a line, the lowest priority number wins.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
namestringrequired | A name for the rule. |
containsstringrequired | Text to look for in the bank line's description or reference. Case does not matter. |
accountstringrequired | Code of the account the money is for. Not a bank account that has statement lines. |
approved_bystringrequired | Who approved the rule. Entries the rule records are approved in this name. |
directionstring | in (money in only), out (money out only) or any. Defaults to any. |
min_amountinteger | Only lines of at least this size (money in or out), in the smallest currency unit. Above zero. |
max_amountinteger | Only lines of at most this size, in the smallest currency unit. Above zero and not below min_amount. |
memostring | Reason written on entries the rule records. Defaults to the bank line's description. |
auto_recordboolean | Record matching lines without a person. Defaults to false. |
priorityinteger | Lower numbers are tried first. Defaults to 100. |
Example
{
"name": "Kahramaa electricity and water",
"contains": "KAHRAMAA",
"account": "6200",
"approved_by": "Khalid Al-Thani",
"direction": "out",
"max_amount": 100000,
"memo": "Kahramaa bill, Al Sadd shop",
"auto_record": true,
"priority": 10
}
Returns
201 with the rule: id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "name", "contains", "account" or "approved_by" is missing
- 400 invalid_request when "direction" is not in, out or any, "min_amount" or "max_amount" is not a whole number above zero, "auto_record" is not true or false, or "priority" is not a whole number
- 422 rejected when the account is not a switched-on account of this business, or is a bank account with statement lines
- 422 rejected when min_amount is above max_amount
POST/v1/businesses/{business}/rules/{rule}/switch-off
Stops a rule from suggesting or recording. The rule is kept so past auto-coding can still be traced to it. No request body is needed.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
rule | The rule id. |
Returns
200 with the rule (id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at), with is_active false.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the rule is not in this business
POST/v1/businesses/{business}/rules/apply
Goes through the unmatched bank lines, oldest first, and records each one whose best-fitting rule has auto_record switched on. A line that already has a possible match in the books is left for a person to match. The same run also happens on its own each day.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
bystring | Who to name as preparing the entries. Defaults to auto-coding. |
Example
{
"by": "Fatima Al-Kuwari"
}
Returns
200 with lines_recorded: how many bank lines were recorded and matched.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 422 rejected when a line to be recorded falls in a closed month or its rule's account has been switched off
Reconciliation
GET/v1/businesses/{business}/reconciliations
Lists every reconciliation, latest statement date first, including finished and undone ones.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list, each with id, account, statement_date, statement_balance, status (open, finished or undone), finished_by and finished_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/reconciliations
Starts reconciling a bank, cash or card account against a statement balance on a date. It starts from where the last finished reconciliation ended, and book lines already matched to imported bank lines are ticked to begin with. Only one reconciliation per account can be open at a time.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
accountstringrequired | Code of the asset or liability account (bank, cash or card). |
statement_datedaterequired | Date of the statement balance. Must be after the last finished reconciliation of this account. |
statement_balanceintegerrequired | The balance the statement shows, in the smallest currency unit. May be negative. |
bystringrequired | Who started it. |
Example
{
"account": "1010",
"statement_date": "2026-11-30",
"statement_balance": 4956500,
"by": "Fatima Al-Kuwari"
}
Returns
201 with the reconciliation: id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]. lines are the account's book lines up to the statement date not ticked by an earlier finished reconciliation.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "statement_balance" is not a whole number, "statement_date" is not a date, or "account" or "by" is missing
- 422 rejected when the account is not an asset or liability account of this business
- 422 rejected when a reconciliation of the account is already open
- 422 rejected when the account is already reconciled to that date or later
GET/v1/businesses/{business}/reconciliations/{rec}
Returns one reconciliation with its lines, which are ticked, and how far the ticked lines are from the statement balance.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
rec | The reconciliation id. |
Returns
200 with id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}].
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the reconciliation is not in this business
POST/v1/businesses/{business}/reconciliations/{rec}/finish
Closes the reconciliation once the ticked lines come exactly to the statement balance. Its ticked lines then count as reconciled, and the next reconciliation of the account starts from this statement balance.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
rec | The reconciliation id. |
Body
bystringrequired | Who finished it. |
Example
{
"by": "Fatima Al-Kuwari"
}
Returns
200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]), with status finished.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the reconciliation is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "by" is missing
- 422 rejected when the reconciliation is not open
- 422 rejected when the ticked lines are still some amount away from the statement balance (difference is not 0)
POST/v1/businesses/{business}/reconciliations/{rec}/tick
Ticks the book lines the statement also shows, or unticks them. Only lines of the reconciled account, dated up to the statement date and not reconciled before, can be ticked.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
rec | The reconciliation id. |
Body
line_idsarrayrequired | Ids of the lines, from the reconciliation's lines. |
tickedboolean | false to untick. Defaults to true. |
Example
{
"line_ids": [
"01934f6e-2b7a-7c41-9d3e-5a8f0c2e7b19",
"01934f6e-2b7b-7d02-8a6f-1c3e5b7d9f20"
],
"ticked": true
}
Returns
200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the reconciliation is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "line_ids" is not a list of ids
- 422 rejected when the reconciliation is not open
- 422 rejected when a line is not on this account, is dated after the statement date, or was reconciled before
POST/v1/businesses/{business}/reconciliations/{rec}/undo
Undoes the latest reconciliation of an account, open or finished, so its lines can be reconciled again. Its ticks are kept for the record but no longer count.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
rec | The reconciliation id. |
Body
bystringrequired | Who undid it. |
Example
{
"by": "Khalid Al-Thani"
}
Returns
200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]), with status undone.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the reconciliation is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "by" is missing
- 422 rejected when it is already undone
- 422 rejected when a later reconciliation of the same account exists
POST/v1/businesses/{business}/revaluations
At a month end, restates what customers owe and what the business owes on open invoices, bills and credits in other currencies at that day's rate. The difference goes to exchange gains and losses and is turned back the next day, so later payments settle against the original amounts. Nothing is recorded when nothing changed.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
as_ofdaterequired | The day to revalue at, usually a month end. |
created_bystringrequired | Who prepared it. |
approved_bystringrequired | Who approved the entry and its turning back. |
Example
{
"as_of": "2026-11-30",
"created_by": "Fatima Al-Kuwari",
"approved_by": "Khalid Al-Thani"
}
Returns
201 with as_of, entry_id (the revaluation entry) and changed true when an entry was recorded; 200 with entry_id null and changed false when nothing needed restating.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "as_of" is not a date, or "created_by" or "approved_by" is missing
- 422 rejected when there is no exchange rate for one of the currencies on that day
- 422 rejected when the month of as_of, or of the day after, is closed
Quotes and purchase orders
GET/v1/businesses/{business}/orders
Lists up to 200 quotes and purchase orders, newest issue date first.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
kindstring | quote or purchase_order. |
statusstring | open, accepted, declined, converted or cancelled. |
Returns
200 with data: a list, each with id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "kind" or "status" is not one of the allowed values
POST/v1/businesses/{business}/orders
Saves a quote for a customer or a purchase order to a supplier. Quotes and orders are promises, not money, so they never touch the books. Each kind is numbered in turn (QUO-000001, PO-000001) and the total is worked out from the lines, with tax.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
kindstringrequired | quote or purchase_order. |
contact_idstringrequired | The customer (for a quote) or supplier (for a purchase order). |
issue_datedaterequired | Date of the quote or order. |
valid_untildate | When a quote expires, or when a purchase order is expected. Not before issue_date. |
referencestring | Your or the contact's reference. |
memostring | A note. |
created_bystringrequired | Who prepared it. |
currencystring | Three-letter currency code. Defaults to the business's own currency. |
linesarrayrequired | At least one line, in the same shape a draft invoice or bill takes. |
lines[].accountstring | Account code the line goes to (for example 4000 for sales). Needed when the line has no "item". |
lines[].itemstring | Stock item code, instead of an account. The item must be in the business's stock list and switched on. |
lines[].descriptionstring | What the line is for. |
lines[].quantitynumber | How many. Defaults to 1 and must be above zero. |
lines[].unit_priceintegerrequired | Price of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero. |
lines[].discountinteger | Discount off the line as an amount. It must be below the line's price. |
lines[].discount_percentnumber | Discount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both. |
lines[].taxstring | Tax code for the line. Leave the field out to use the contact's default tax code; send null for no tax. |
lines[].branchstring | Branch name or id for the line. |
lines[].projectstring | Project name or id for the line. |
Example
{
"kind": "quote",
"contact_id": "01934f6e-0c11-7a52-8e4b-2f6d9a1c3e70",
"issue_date": "2026-11-16",
"valid_until": "2026-11-30",
"reference": "Majlis fit-out, Al Waab villa",
"memo": "Price includes delivery within Doha",
"created_by": "Noora Al-Mannai",
"lines": [
{
"account": "4000",
"description": "Majlis seating, 8 seats",
"quantity": 1,
"unit_price": 1850000
},
{
"account": "4000",
"description": "Installation",
"quantity": 2,
"unit_price": 75000,
"discount_percent": 10
}
]
}
Returns
201 with the quote or order: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "kind" is not quote or purchase_order, "contact_id" is not an id, "issue_date" or "valid_until" is not a date, or "created_by" is missing
- 400 invalid_request when "lines" is missing or an empty list
- 422 rejected when the contact is not in this business, a quote is for a supplier, or a purchase order is to a customer
- 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line
- 422 rejected when valid_until is before issue_date
GET/v1/businesses/{business}/orders/{order}
Returns one quote or purchase order with its lines and, once converted, the id of the invoice or bill it became.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
order | The quote or purchase order id. |
Returns
200 with id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the quote or order is not in this business
PUT/v1/businesses/{business}/orders/{order}
Replaces the lines, expiry, reference and memo of a quote or order that is still open, and works the total out again. Fields you leave out are cleared, so send them all. The contact, kind and date cannot change.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
order | The quote or purchase order id. |
Body
valid_untildate | New expiry or expected date. Cleared if left out. |
referencestring | New reference. Cleared if left out. |
memostring | New note. Cleared if left out. |
linesarrayrequired | The full new set of lines. |
lines[].accountstring | Account code the line goes to (for example 4000 for sales). Needed when the line has no "item". |
lines[].itemstring | Stock item code, instead of an account. The item must be in the business's stock list and switched on. |
lines[].descriptionstring | What the line is for. |
lines[].quantitynumber | How many. Defaults to 1 and must be above zero. |
lines[].unit_priceintegerrequired | Price of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero. |
lines[].discountinteger | Discount off the line as an amount. It must be below the line's price. |
lines[].discount_percentnumber | Discount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both. |
lines[].taxstring | Tax code for the line. Leave the field out to use the contact's default tax code; send null for no tax. |
lines[].branchstring | Branch name or id for the line. |
lines[].projectstring | Project name or id for the line. |
Example
{
"valid_until": "2026-12-07",
"reference": "Majlis fit-out, Al Waab villa",
"memo": "Revised after site visit",
"lines": [
{
"account": "4000",
"description": "Majlis seating, 10 seats",
"quantity": 1,
"unit_price": 2200000
},
{
"account": "4000",
"description": "Installation",
"quantity": 2,
"unit_price": 75000
}
]
}
Returns
200 with the updated quote or order: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the quote or order is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "valid_until" is not a date
- 400 invalid_request when "lines" is missing or an empty list
- 422 rejected when the quote or order is not open (accepted, declined, converted or cancelled ones can no longer change)
- 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line
- 422 rejected when valid_until is before the issue date
POST/v1/businesses/{business}/orders/{order}/convert
Makes a draft invoice from a quote, or a draft bill from a purchase order, with the same contact, lines, currency and memo, and marks it converted. The draft still needs approving before it reaches the books.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
order | The quote or purchase order id. |
Body
bystringrequired | Who prepared the draft. |
issue_datedate | Date of the invoice or bill. Defaults to today in the business's time zone. |
due_datedate | When it is due. Defaults to the issue date. |
Example
{
"by": "Noora Al-Mannai",
"issue_date": "2026-11-20",
"due_date": "2026-12-20"
}
Returns
201 with order (the quote or order, now converted: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at) and document_id (the new draft).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the quote or order is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "by" is missing, or "issue_date" or "due_date" is not a date
- 422 rejected when the quote or order is declined, converted or cancelled
- 422 rejected when a line no longer passes the draft's checks (an account, item or tax code switched off), or there is no exchange rate for a foreign currency
POST/v1/businesses/{business}/orders/{order}/status
Notes that a quote was accepted or declined, or that a quote or order was cancelled, or puts it back to open. A purchase order stays open until the bill comes, so it cannot be accepted. To mark one converted, use convert.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
order | The quote or purchase order id. |
Body
statusstringrequired | accepted, declined, cancelled or open. |
bystringrequired | Who changed it. |
Example
{
"status": "accepted",
"by": "Noora Al-Mannai"
}
Returns
200 with the quote or order (id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the quote or order is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "status" is not accepted, declined, cancelled or open, or "by" is missing
- 422 rejected when it is already converted or cancelled
- 422 rejected when accepting a purchase order
Repeating documents
GET/v1/businesses/{business}/recurring
Lists every template, the next one due first. A template that failed when it ran shows the reason in last_error and is switched off.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of templates, each with id, name, kind, contact_id, money_account, lines, reference, memo, currency, every, every_n, next_date, end_date, due_days, auto_record, approved_by, is_active, last_error, created_by, created_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/recurring
Saves a template that makes an invoice, bill, expense or cash sale on a regular date, such as monthly rent. Each time it makes a draft, or records it straight away when auto_record is true and someone approved that once here. The template is checked now with the same rules a draft uses.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
namestringrequired | A name for the template, for example "Shop rent, Souq Waqif". |
kindstringrequired | invoice, bill, expense or cash_sale. |
contact_idstring | The customer or supplier. Needed for invoices and bills. |
everystringrequired | week, month, quarter or year. |
every_ninteger | Repeat every this many weeks, months, quarters or years, 1 to 12. Defaults to 1. |
start_datedaterequired | Date of the first document. |
end_datedate | No documents after this date. Not before start_date. |
due_daysinteger | Days from the document date to its due date, 0 to 365. Defaults to 0. |
money_accountstring | For an expense or cash sale: the bank or cash account code it is paid from or into (an expense may also use the owner's equity account). Leave out for invoices and bills. |
referencestring | Reference put on each document. |
memostring | Memo put on each document. Defaults to the template name. |
currencystring | Three-letter currency code. Defaults to the business's own currency. |
auto_recordboolean | Record each document without waiting for approval. Defaults to false. |
approved_bystring | Who agreed that documents are recorded on their own. Needed when auto_record is true. |
created_bystringrequired | Who set the template up. |
linesarrayrequired | At least one line, in the same shape a draft takes. |
lines[].accountstring | Account code the line goes to (for example 4000 for sales). Needed when the line has no "item". |
lines[].itemstring | Stock item code, instead of an account. The item must be in the business's stock list and switched on. |
lines[].descriptionstring | What the line is for. |
lines[].quantitynumber | How many. Defaults to 1 and must be above zero. |
lines[].unit_priceintegerrequired | Price of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero. |
lines[].discountinteger | Discount off the line as an amount. It must be below the line's price. |
lines[].discount_percentnumber | Discount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both. |
lines[].taxstring | Tax code for the line. Leave the field out to use the contact's default tax code; send null for no tax. |
lines[].branchstring | Branch name or id for the line. |
lines[].projectstring | Project name or id for the line. |
Example
{
"name": "Shop rent, Souq Waqif",
"kind": "bill",
"contact_id": "01934f6e-41d2-7f08-b3a6-7c90e15d2a44",
"every": "month",
"start_date": "2026-12-01",
"end_date": "2027-11-01",
"due_days": 5,
"reference": "Lease SW-114",
"auto_record": true,
"approved_by": "Khalid Al-Thani",
"created_by": "Fatima Al-Kuwari",
"lines": [
{
"account": "6000",
"description": "Monthly rent",
"unit_price": 1200000,
"tax": null
}
]
}
Returns
201 with the template: id, name, kind, contact_id, money_account, lines, reference, memo, currency, every, every_n, next_date, end_date, due_days, auto_record, approved_by, is_active, last_error, created_by, created_at. next_date is the date of the next document.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "name", "start_date" or "created_by" is missing, "kind" or "every" is not one of the allowed values, "every_n" is not 1 to 12, "due_days" is not 0 to 365, "auto_record" is not true or false, "contact_id" is not an id, or a date is malformed
- 400 invalid_request when "lines" is missing or an empty list
- 422 rejected when end_date is before start_date, or auto_record is true without approved_by
- 422 rejected when an invoice or bill has no contact, the contact is not in this business, or it is on the wrong side (a supplier on a sale, a customer on a purchase)
- 422 rejected when a money account is given for an invoice or bill, or it is not a switched-on bank or cash account
- 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line
POST/v1/businesses/{business}/recurring/{template}/switch-off
Stops a template from making any more documents. Documents it already made are not touched. No request body is needed.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
template | The repeating document (template) id. |
Returns
200 with id and is_active (false).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the repeating document is not in this business
POST/v1/businesses/{business}/recurring/run
Makes every document due up to a date from the switched-on templates, catching up on any missed dates, and never makes the same date twice. A template that fails (an account switched off, a month closed) keeps the error, is switched off, and the others carry on. This also runs on its own each morning from 6:00.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
datedate | Make documents dated up to this day. Defaults to today (UTC). |
Example
{
"date": "2026-12-01"
}
Returns
200 with documents_made: how many documents were made.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "date" is not a date like 2026-11-05
Spread costs and income
GET/v1/businesses/{business}/schedules
Lists every schedule, earliest start first, with how many months have been recorded and how much has moved.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of schedules, each with id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/schedules
Sets up a schedule that moves an amount a share at a time from a holding account to where it belongs. A prepaid cost (a year's rent paid upfront) moves from an asset account to an expense; deferred income (a year's service paid in advance by a customer) moves from a liability account to income. It only moves the amount; record the payment itself separately.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
kindstringrequired | prepaid (a cost paid in advance) or deferred (income received in advance). |
descriptionstringrequired | What is being spread. Each month's entry is named "<description>, month N of M". |
totalintegerrequired | The whole amount, in the smallest currency unit. Above zero. The monthly shares add up to exactly this. |
start_monthdaterequired | Any day in the first month. The schedule starts on the first of that month. |
monthsintegerrequired | How many months, 1 to 120. |
target_accountstringrequired | Code of the account each share moves to: an expense account for prepaid, an income account for deferred. |
holding_accountstring | Code of the account the amount waits in: an asset for prepaid, a liability for deferred. Defaults to 1300 (paid in advance) for prepaid, and to 2150 Income received in advance for deferred, which is added the first time it is needed. |
document_idstring | The bill or invoice the amount came from, for reference. |
created_bystringrequired | Who set it up. |
approved_bystringrequired | Who approved it. Each month is recorded on its own in this name. |
Example
{
"kind": "prepaid",
"description": "Warehouse rent, Industrial Area, 2027",
"total": 14400000,
"start_month": "2027-01-01",
"months": 12,
"target_account": "6000",
"document_id": "01934f6e-6e0a-7b93-a1c4-0d2b8f5e9c13",
"created_by": "Fatima Al-Kuwari",
"approved_by": "Khalid Al-Thani"
}
Returns
201 with the schedule: id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "kind" is not prepaid or deferred, "months" is not 1 to 120, "total" is not a whole number above zero, "start_month" is not a date, "document_id" is not an id, or "description", "target_account", "created_by" or "approved_by" is missing
- 422 rejected when either account is not in the books or is switched off (including a prepaid schedule with no holding account given and no account 1300)
- 422 rejected when the accounts are the wrong types: prepaid needs an asset and an expense account, deferred a liability and an income account
- 422 rejected when document_id is not a document of this business
POST/v1/businesses/{business}/schedules/{schedule}/stop
Stops a running schedule so no more months are recorded. Months already recorded stay in the books, and what has not moved stays in the holding account.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
schedule | The schedule id. |
Body
bystringrequired | Who stopped it. |
Example
{
"by": "Khalid Al-Thani"
}
Returns
200 with the schedule (id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far)), with status stopped.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the schedule is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "by" is missing
- 422 rejected when the schedule is not running (already done or stopped)
POST/v1/businesses/{business}/schedules/run
Records each running schedule's share for every month up to and including the given month that is not recorded yet. Each share is dated the last day of its month. A schedule whose months are all recorded becomes done. This also runs on its own once a month has turned.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
through_monthdaterequired | Any day in the last month to record. |
bystring | Who to name as preparing the entries. Defaults to api. |
Example
{
"through_month": "2027-01-31",
"by": "Fatima Al-Kuwari"
}
Returns
200 with entries_recorded: how many monthly entries were recorded.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "through_month" is not a date like 2026-11-05
- 422 rejected when a share falls in a closed month or one of the schedule's accounts has been switched off
Branches and projects
GET/v1/businesses/{business}/branches
Lists the business's branches in name order, switched on or off.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of branches, each with id, name, name_ar, contact_id and is_active.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/branches
Adds a branch, such as a second shop or kitchen, so lines can be tagged with it and profit seen for each one. Tags do not change how the books balance.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
namestringrequired | Branch name. Must be unique among the business's branches, ignoring case. |
name_arstring | Name in Arabic. |
Example
{
"name": "The Pearl",
"name_ar": "اللؤلؤة"
}
Returns
201 with id, name, name_ar, contact_id (always null for a branch) and is_active.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "name" is missing
- 422 rejected when there is already a branch with that name
POST/v1/businesses/{business}/documents/{document}/tags
Sets the branch and project of a draft document, used for its lines that do not name their own. Both are set on every call, so a field you leave out is cleared.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
document | The draft document id. |
Body
branchstring | Branch name or id. Cleared if left out. |
projectstring | Project name or id. Cleared if left out. |
Example
{
"branch": "The Pearl",
"project": "Lusail villa fit-out"
}
Returns
200 with id, branch (name or null) and project (name or null).
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the document is not in this business
- 400 invalid_request when the body is not a JSON object
- 422 rejected when the document is not a draft
- 422 rejected when no branch or project has that name or id, or it is switched off
GET/v1/businesses/{business}/projects
Lists the business's projects in name order, switched on or off.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of projects, each with id, name, name_ar, contact_id and is_active.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/projects
Adds a project, such as a fit-out or an event, so its income and costs can be tagged and seen together. A project can name the customer it is for.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
namestringrequired | Project name. Must be unique among the business's projects, ignoring case. |
name_arstring | Name in Arabic. |
contact_idstring | The customer the project is for, one of this business's contacts. |
Example
{
"name": "Lusail villa fit-out",
"name_ar": "تجهيز فيلا لوسيل",
"contact_id": "01934f6e-0c11-7a52-8e4b-2f6d9a1c3e70"
}
Returns
201 with id, name, name_ar, contact_id and is_active.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "name" is missing or "contact_id" is not an id
- 422 rejected when there is already a project with that name
- 422 rejected: contact_id is not one of this business's contacts.
Budgets
GET/v1/businesses/{business}/budgets
Lists the business's budgets in name order.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Returns
200 with data: a list of budgets, each with id, name, created_by and created_at.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
POST/v1/businesses/{business}/budgets
Creates an empty, named budget: what the owner expects to earn and spend. Add the figures with the budget lines endpoint.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Body
namestringrequired | Budget name, unique in the business, for example "2027 plan". |
created_bystringrequired | Who made it. |
Example
{
"name": "2027 plan",
"created_by": "Khalid Al-Thani"
}
Returns
201 with id and name.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "name" or "created_by" is missing
- 409 conflict when the business already has a budget with that name
PUT/v1/businesses/{business}/budgets/{budget}/lines
Sets the budgeted amount for an income or expense account in a month, optionally for one branch. Each figure replaces any earlier one for the same account, month and branch; an amount of null clears it. Figures you do not send are left as they are.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
budget | The budget id. |
Body
linesarrayrequired | 1 to 600 figures. |
lines[].accountstringrequired | Code of an income or expense account. |
lines[].monthdaterequired | Any day in the month. Saved as the first of the month. |
lines[].amountintegerrequired | Expected income or spending for the month, in the smallest currency unit, or null to clear the figure. |
lines[].branchstring | Branch name or id, for a branch's own figure. |
Example
{
"lines": [
{
"account": "4000",
"month": "2027-01-01",
"amount": 15000000
},
{
"account": "6000",
"month": "2027-01-01",
"amount": 1200000
},
{
"account": "4000",
"month": "2027-01-01",
"amount": 4500000,
"branch": "The Pearl"
}
]
}
Returns
200 with id, name and lines: every figure in the budget, each with account, month, branch and amount.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the budget is not in this business
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "lines" is not a list of 1 to 600 figures, an amount is not a whole number or null, a month is not a date, or an account is missing
- 422 rejected when an account is not in the books or is not an income or expense account
- 422 rejected when a branch does not exist or is switched off
GET/v1/businesses/{business}/budgets/{budget}/vs-actual
For each income and expense account with a budget figure or actual activity, compares the budget for the months in the period with what the books show. Income is shown as credits less debits and expenses as debits less credits, so both are normally positive.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
budget | The budget id. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
branchstring | Branch name or id, to compare one branch only. |
Returns
200 with budget (name), from, to, currency and accounts [{code, name, type (income or expense), budget, actual, difference (actual less budget)}], income accounts first.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 404 not_found when the budget is not in this business
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
- 422 rejected when the branch does not exist or is switched off
Stock
GET/v1/businesses/{business}/items
Lists every item of the business, including switched-off ones, sorted by code, with how many are on hand and what they are worth.
Path
Returns
200 with data: an array of items, each with id, code, name, name_ar, unit, is_active, stock_account, sales_account, cost_account, on_hand, value, average_cost and created_at.
Errors
- 404 not_found when the business does not exist or is not visible to this key
POST/v1/businesses/{business}/items
Adds an item the business buys and sells. Stock is valued at weighted average cost and moves when a bill, receipt, invoice or cash sale with this item on a line is approved, and through counts and opening stock. The item starts with nothing on hand.
Path
Body
codestringrequired | Up to 40 letters, numbers, dots, dashes or underscores. Document lines refer to the item by this code. |
namestringrequired | The item's name. |
name_arstring | The name in Arabic. |
unitstring | The unit it is counted in, like box or kg. Defaults to each. |
stock_accountstring | Code of the asset account that holds its value. Defaults to 1200. |
sales_accountstring | Code of the income account sales go to. Defaults to 4000. |
cost_accountstring | Code of the expense account the cost of what is sold goes to. Defaults to 5000. |
Example
{
"code": "RICE-5KG",
"name": "Basmati rice 5 kg",
"name_ar": "أرز بسمتي 5 كغ",
"unit": "bag"
}
Returns
201 with the item: id, code, name, name_ar, unit, is_active, stock_account, sales_account, cost_account, on_hand, value, average_cost (null when nothing is on hand) and created_at.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "code" or "name" is missing or not text
- 400 invalid_request when the code is not up to 40 letters, numbers, dots, dashes or underscores
- 409 conflict when an item with this code already exists
- 422 rejected when an account code is not in this business's books, or is not the right type (asset for stock, income for sales, expense for cost)
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/items/{item}
Returns one item with what is on hand and its latest 100 stock movements, newest first.
Path
business | The business id. |
item | The item id (not its code). |
Returns
200 with the item fields (id, code, name, unit, on_hand, value, average_cost and the rest) and movements, each with date, reason (purchase, sale, count, opening or void), quantity (negative when stock went out), value, document_number, created_by and created_at.
Errors
- 404 not_found when the business does not exist or is not visible to this key
- 404 not_found when the item does not exist in this business
POST/v1/businesses/{business}/items/{item}/count
Sets what is on hand to the number counted and records the difference in the books. A shortfall is taken out at average cost and charged to the cost account; extra stock found is added at average cost, or at unit_cost when none was on hand. A count that matches what is on hand changes nothing.
Path
business | The business id. |
item | The item id. |
Body
datedaterequired | The day of the count. |
countednumberrequired | How many were counted, zero or more. Fractions are allowed. |
bystringrequired | Who counted. |
reasonstring | A note added to the entry, like damaged in storage. |
unit_costinteger | Cost of one unit in the smallest currency unit, above zero. Needed when stock is found and none was on hand. |
Example
{
"date": "2026-11-30",
"counted": 46,
"by": "Fatima Al-Kuwari",
"reason": "Four bags torn in the store room"
}
Returns
200 with the item after the count: on_hand, value, average_cost and the other item fields.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "date" is not a date like 2026-11-05
- 400 invalid_request when "counted" is not a number of zero or more
- 400 invalid_request when "by" is missing
- 400 invalid_request when "unit_cost" is given but is not a whole number above zero
- 422 rejected when stock was found, none was on hand and no unit_cost was given
- 422 rejected when the month of the date is closed
- 404 not_found when the business or item does not exist
POST/v1/businesses/{business}/items/{item}/opening
Puts the stock a business already had into the books when it starts using BasePipe, against the opening balances account (3900). Only allowed before the item has any stock movements; after that, use a stock count.
Path
business | The business id. |
item | The item id. |
Body
datedaterequired | The day the opening stock is recorded on. |
quantitynumberrequired | How many were on hand, above zero. |
unit_costintegerrequired | Cost of one unit in the smallest currency unit, above zero. |
bystringrequired | Who recorded it. |
Example
{
"date": "2026-11-01",
"quantity": 50,
"unit_cost": 2850,
"by": "Fatima Al-Kuwari"
}
Returns
201 with the item: on_hand, value, average_cost and the other item fields.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "date" is not a date like 2026-11-05
- 400 invalid_request when "quantity" is not a number above zero
- 400 invalid_request when "unit_cost" is not a whole number above zero
- 400 invalid_request when "by" is missing
- 422 rejected when the item already has stock movements
- 422 rejected when the business has no opening balances account (3900)
- 422 rejected when the month of the date is closed
- 404 not_found when the business or item does not exist
GET/v1/businesses/{business}/reports/stock-on-hand
Returns what is on the shelf now, item by item at average cost, and the total value. It also checks each stock account in the books against the value of the stock on hand and lists any that differ. This report returns JSON only.
Path
Returns
200 with currency, total_value, items (each with code, name, unit, on_hand, value and average_cost) and mismatches (each with account, in_books and on_hand; empty when the books agree with the shelf).
Errors
- 404 not_found when the business does not exist or is not visible to this key
Equipment
GET/v1/businesses/{business}/equipment
Lists all the business's equipment, active and sold or scrapped, oldest purchase first, with wear and tear to date and book value.
Path
Returns
200 with data: an array of equipment, each with the same fields as a single piece of equipment (id, name, status, cost, monthly_amount, worn, book_value, months_recorded and the rest).
Errors
- 404 not_found when the business does not exist or is not visible to this key
POST/v1/businesses/{business}/equipment
Registers a piece of equipment and approves its straight-line wear and tear schedule. Nothing is posted to the books until the monthly run records each month's wear and tear. Wear and tear starts the month after purchase unless start_month says otherwise.
Path
Body
namestringrequired | What the equipment is. |
purchase_datedaterequired | The day it was bought. |
costintegerrequired | What it cost, in the smallest currency unit, above zero. |
useful_life_monthsintegerrequired | How many months it will be used, from 1 to 600. |
approved_bystringrequired | Who approved the schedule. |
residualinteger | What it will be worth at the end, in the smallest currency unit. Defaults to 0. |
start_monthstring | First month of wear and tear, like 2026-12. Defaults to the month after purchase. |
opening_worninteger | Wear and tear already counted before BasePipe, in the smallest currency unit. Defaults to 0. |
purchase_document_idstring | Id of the recorded bill or receipt it was bought on. |
asset_accountstring | Code of the asset account for its cost. Defaults to 1500. |
worn_accountstring | Code of the asset account for wear and tear to date. Defaults to 1510. |
expense_accountstring | Code of the expense account for monthly wear and tear. Defaults to 6800. |
Example
{
"name": "Toyota Hiace delivery van",
"purchase_date": "2026-11-10",
"cost": 12000000,
"useful_life_months": 60,
"residual": 2400000,
"approved_by": "Khalid Al-Thani"
}
Returns
201 with the equipment: id, name, status (active), purchase_date, cost, residual, opening_worn, useful_life_months, start_month, end_month, monthly_amount, worn, book_value, months_recorded, last_month_recorded, asset_account, worn_account, expense_account, purchase_document_id, approved_by, created_at, and the disposal fields (null).
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "useful_life_months" is not a whole number from 1 to 600
- 400 invalid_request when "name" or "approved_by" is missing
- 400 invalid_request when "purchase_date" is not a date like 2026-11-05
- 400 invalid_request when "cost", "residual" or "opening_worn" is not a whole number above zero in the smallest currency unit
- 400 invalid_request when "start_month" is not a month like 2026-11
- 400 invalid_request when "purchase_document_id" is not an id
- 422 rejected when the purchase document is not a recorded bill or receipt of this business
- 422 rejected when residual plus opening_worn is not less than cost
- 422 rejected when an account code is not in this business's books or is not the right type
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/equipment/{asset}
Returns one piece of equipment with every month of wear and tear recorded so far, oldest first.
Path
business | The business id. |
asset | The equipment id. |
Returns
200 with the equipment fields (status is active or disposed; book_value is 0 once disposed) and wear_and_tear, each with month (like 2026-12), month_no, amount and entry_id.
Errors
- 404 not_found when the business does not exist or is not visible to this key
- 404 not_found when the equipment does not exist in this business
POST/v1/businesses/{business}/equipment/{asset}/dispose
Records that equipment was sold or scrapped and posts the gain or loss. Wear and tear is brought up to date to the month before; none is counted for the month it goes. Leave out proceeds, or send 0, when it was scrapped for nothing.
Path
business | The business id. |
asset | The equipment id. |
Body
datedaterequired | The day it was sold or scrapped. Must be on or after the purchase date. |
bystringrequired | Who approved it. |
proceedsinteger | Money received, in the smallest currency unit. Defaults to 0. |
money_accountstring | Code of the asset account the money went into. Needed when proceeds is above zero. |
memostring | A note for the entry. |
Example
{
"date": "2026-11-20",
"proceeds": 350000,
"money_account": "1010",
"by": "Khalid Al-Thani",
"memo": "Sold old espresso machine to Souq Waqif cafe"
}
Returns
200 with the equipment after disposal: status disposed, disposed_on, disposed_by, disposal_proceeds, book_value 0 and the other equipment fields.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "proceeds" is not a whole number above zero in the smallest currency unit
- 400 invalid_request when "money_account" is missing and proceeds is above zero
- 400 invalid_request when "date" is not a date like 2026-11-05, or "by" is missing
- 422 rejected when the equipment has already been sold or scrapped
- 422 rejected when the date is before the purchase date
- 422 rejected when "money_account" is not an asset account in this business's books
- 422 rejected when the month of the date is closed
- 404 not_found when the business or equipment does not exist
POST/v1/businesses/{business}/equipment/run-wear-and-tear
Records every month of wear and tear due on active equipment up to and including the given month that is not recorded yet, oldest first, each dated the last day of its month. BasePipe's scheduler calls this at each month end. It is safe to call again: months already recorded are skipped.
Path
Body
through_monthstringrequired | The last month to record, like 2026-11. |
bystring | Who ran it. Defaults to scheduler. |
Example
{
"through_month": "2026-11",
"by": "Khalid Al-Thani"
}
Returns
200 with through_month and entries_recorded (how many monthly entries were posted; 0 when nothing was due).
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "through_month" is not a month like 2026-11
- 400 invalid_request when "by" is not text
- 422 rejected when a month that needs an entry is closed
- 404 not_found when the business does not exist or is not visible to this key
Tax
POST/v1/businesses/{business}/details
Sets the details an electronic invoice will need and the share of the business owned by non-Qatari, non-GCC owners, which the income tax estimate uses. Only the fields you send change; leaving a field out keeps its current value.
Path
Body
legal_namestring | The registered legal name. |
tax_numberstring | The tax number from the General Tax Authority. |
commercial_registrationstring | The commercial registration (CR) number. |
addressstring | The business address. |
foreign_ownership_pctnumber | Percentage owned by non-Qatari, non-GCC owners, from 0 to 100. Defaults to 0. |
Example
{
"legal_name": "Al Waab Trading W.L.L.",
"tax_number": "5000123456",
"commercial_registration": "145678",
"address": "Building 12, Street 340, Al Waab, Doha, Qatar",
"foreign_ownership_pct": 49
}
Returns
200 with name, legal_name, tax_number, commercial_registration, address and foreign_ownership_pct.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when a text field is not text
- 400 invalid_request when "foreign_ownership_pct" is not a number from 0 to 100
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/reports/tax
Returns the tax charged, paid and withheld by tax code over a period, the withholding owed by month with its due date (the 16th of the next month), what the books show as still owed to the tax authority on the end date, and a rough income tax estimate. The estimate is 10% of this financial year's profit so far on the foreign-owned share; it is a guide, not a return. This report returns JSON only.
Path
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period. Defaults to today (UTC). |
Returns
200 with from, to, currency, codes (each with code, name, kind, rate, documents, taxable and tax, from recorded documents issued in the period), withholding_by_month (each with month as the first day of the month, withheld, due_by and documents), still_owed (withholding and sales_tax) and income_tax_estimate (year_starts, profit_so_far, foreign_ownership_pct and estimate).
Errors
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05
- 400 invalid_request when "from" is after "to"
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/tax-codes
Lists the business's tax codes, sorted by kind and then code. A kind is output (tax charged on sales), input (tax paid on purchases that can be reclaimed) or withholding (tax kept back from a supplier's payment and owed to the authority).
Path
Returns
200 with data: an array of tax codes, each with code, name, name_ar, kind, rate (a percentage, like 5), account (the account code the tax goes to) and is_active.
Errors
- 404 not_found when the business does not exist or is not visible to this key
POST/v1/businesses/{business}/tax-codes
Adds a tax code that invoice, bill and receipt lines can carry. Without an account, the tax goes to 2300 Withholding tax owed, 2310 Sales tax owed or 1310 Sales tax to reclaim, depending on the kind; the account is added to the books the first time it is needed. The code is stored in capital letters.
Path
Body
codestringrequired | Up to 20 capital letters, numbers, dashes or underscores, like WHT5. Lower case is turned into capitals. |
namestringrequired | What the code is called. |
kindstringrequired | output, input or withholding. |
ratenumberrequired | A percentage above 0 and below 100, like 5. |
name_arstring | The name in Arabic. |
accountstring | Code of an active account in this business's books to post the tax to. Defaults by kind as described above. |
Example
{
"code": "WHT5",
"name": "Withholding tax 5% (non-resident services)",
"name_ar": "ضريبة الاستقطاع 5% (خدمات غير المقيمين)",
"kind": "withholding",
"rate": 5
}
Returns
201 with code, name, kind, rate and account.
Errors
- 400 invalid_request when the body is not a JSON object
- 400 invalid_request when "code" or "name" is missing or not text
- 400 invalid_request when "kind" is not output, input or withholding
- 400 invalid_request when "rate" is not a number above 0 and below 100
- 400 invalid_request when the code is not up to 20 capital letters, numbers, dashes or underscores
- 409 conflict when a tax code with this code already exists for the business
- 422 rejected when "account" is not an active account in this business's books
- 404 not_found when the business does not exist or is not visible to this key
POST/v1/businesses/{business}/tax/setup-qatar
Adds the WHT5 tax code for Qatar's 5% withholding tax on payments to non-residents for services, posting to 2300 Withholding tax owed. Qatar has no VAT in force, so no sales tax code is added. Safe to call again: an existing WHT5 is left as it is.
Path
Returns
201 with codes: ["WHT5"].
Errors
- 404 not_found when the business does not exist or is not visible to this key
Reports
GET/v1/businesses/{business}/reports/balance-sheet
Returns what the business owns, owes and the owner's equity on a date, and whether the two sides balance. Send ?format=html for a printable page and ?lang=ar for Arabic.
Path
Query
as_ofdate | The date to report on. Defaults to today (UTC). |
formatstring | json (default) or html. |
langstring | en (default) or ar. |
Returns
200 with report, title, business, currency, lang, as_of, assets (sections for cash and bank, other current assets and equipment, plus total), liabilities (sections owed within a year and after a year, plus total), equity (sections and total), total_liabilities_and_equity and balanced (true when assets equal liabilities plus equity). With format=html, a 200 HTML page instead.
Errors
- 400 invalid_request when "as_of" is not a date like 2026-11-05
- 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/reports/bills-to-pay
Lists recorded bills still unpaid on a date, grouped into age bands by how late they are, plus supplier credits not yet used. Payments and credits dated on or before as_of count.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Query
as_ofdate | The date to report on, YYYY-MM-DD. Defaults to today. |
Returns
200 with the same shape as who-owes-us: as_of, currency, total_outstanding, by_age, items (bills), unused_credits and credits (supplier credits).
Errors
- 400 invalid_request: as_of is not YYYY-MM-DD.
- 404 not_found: the business does not exist or is not visible to this key.
GET/v1/businesses/{business}/reports/cash-flow
Returns cash at the start of a period, the money that came in and went out from running the business, from equipment bought or sold, and from the owner and lenders, and cash at the end. Send ?format=html for a printable page and ?lang=ar for Arabic.
Path
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period. Defaults to today (UTC). |
formatstring | json (default) or html. |
langstring | en (default) or ar. |
Returns
200 with report, title, business, currency, lang, from, to, opening_cash, sections (operating, investing and financing, each with lines and total), net_change, closing_cash and adds_up (true when opening cash plus the change equals closing cash). With format=html, a 200 HTML page instead.
Errors
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05
- 400 invalid_request when "from" is after "to"
- 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/reports/profit-and-loss
Returns income and costs for a period, grouped into sales, cost of sales, running costs, other income and other costs, with gross, operating and net profit. Send ?format=html for a printable page with no BasePipe branding (a browser can save it as PDF) and ?lang=ar for Arabic wording and a right-to-left page.
Path
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period. Defaults to today (UTC). |
formatstring | json (default) or html. |
langstring | en (default) or ar. Changes section labels and uses Arabic account names where they are set. |
Returns
200 with report, title, business, currency, lang, from, to, sections (each with key, label, lines of code, name and amount, and total), gross_profit, operating_profit and net_profit. All amounts are in the business's own currency in the smallest unit. With format=html, a 200 HTML page instead.
Errors
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05
- 400 invalid_request when "from" is after "to"
- 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
- 404 not_found when the business does not exist or is not visible to this key
GET/v1/businesses/{business}/reports/who-owes-us
Lists recorded invoices with money still owed on a date, grouped into age bands by how late they are, plus credit notes not yet used. Payments and credits dated on or before as_of count.
Path
business | Id of the business. Test keys only see practice businesses; live keys only see live ones. |
Query
as_ofdate | The date to report on, YYYY-MM-DD. Defaults to today. |
Returns
200 with as_of; currency (the business's); total_outstanding; by_age [{band, outstanding}] for 'not yet due', '1-30 days late', '31-60 days late', '61-90 days late', 'over 90 days late'; items [{document_id, number, contact {id, name}, issue_date, due_date, total, outstanding, days_overdue, age_band, currency, outstanding_base}]; unused_credits; credits [{document_id, number, contact, issue_date, unused, currency, unused_base}]. Totals are in the business's currency; each item's total and outstanding are in its own currency.
Errors
- 400 invalid_request: as_of is not YYYY-MM-DD.
- 404 not_found: the business does not exist or is not visible to this key.
Ledger reports
GET/v1/businesses/{business}/reports/audit-log
Who did what and when over a period: documents prepared, approved and voided, payments recorded and voided, and events in the books such as entries recorded. Newest first, up to 1,000 events.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
Returns
200 with from, to and events [{at, actor, action, subject, subject_id, detail}].
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
GET/v1/businesses/{business}/reports/changes-in-equity
What the owners' stake was at the start of the period, what they put in and took out, the profit, and the stake at the end.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
Returns
200 with from, to, currency and rows [{line, amount}] in this order: Owners' stake at the start, Put in by owners, Taken out by owners (negative), Profit for the period, Owners' stake at the end.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
GET/v1/businesses/{business}/reports/general-ledger
Every line in each account over a period, with the balance before the period and a running balance. Balances are shown the natural way round: assets and expenses as debits, the rest as credits. Accounts with no balance and no lines are left out.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
accountstring | Only this account code. |
Returns
200 with from, to, currency and accounts [{code, name, opening, closing, lines [{entry_id, entry_number, date, memo, description, debit, credit, balance, branch, project}]}].
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
GET/v1/businesses/{business}/reports/profit-and-loss-by
Income and expenses per account over a period, split into columns by month, branch or project. Lines with no branch or project go under "Not tagged".
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
bystringrequired | month, branch or project. |
Returns
200 with from, to, by, currency, columns (column names in order, such as 2026-10 and 2026-11, or branch names), accounts [{code, name, group, amounts {column: amount}}] and profit {column: income less expenses}.
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
- 400 invalid_request when "by" is missing or not month, branch or project
GET/v1/businesses/{business}/reports/purchases-by-supplier
Net spending per supplier over a period: recorded bills and expenses less supplier credits, before tax, in the business's own currency. Largest first.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
Returns
200 with from, to, currency and rows [{contact_id, contact_name, documents, spent}]. An expense with no contact uses the party name saved on the document, or "No supplier named".
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
GET/v1/businesses/{business}/reports/sales-by-customer
Net sales per customer over a period: recorded invoices and cash sales less credit notes, before tax, in the business's own currency. Largest first.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
Returns
200 with from, to, currency and rows [{contact_id, contact_name, documents (how many), sales}]. Sales with no customer are under "No customer named".
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
GET/v1/businesses/{business}/reports/sales-by-item
Net quantity and sales per item or service over a period, from recorded invoices and cash sales less credit notes, before tax. Lines without an item are grouped under their account. Largest first.
Path
business | The business id. It must belong to you, and a test key only sees practice businesses. |
Query
fromdate | First day of the period. Defaults to the first day of the month that "to" falls in. |
todate | Last day of the period, included. Defaults to today (UTC). |
Returns
200 with from, to, currency and rows [{item_code (null for lines without an item), name, quantity, sales}].
Errors
- 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
- 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
Financial years
POST/v1/businesses/{business}/settings/year-start
Chooses the month the business's financial year starts in. It can't change once any year has been closed.
Path
Body
monthintegerrequired | From 1 (January) to 12 (December). |
bystringrequired | Who made the change. |
Example
{
"month": 4,
"by": "Fatima Al-Kuwari"
}
Returns
200 with starts_in_month.
Errors
- 400 invalid_request: the body is not a JSON object, month is not a whole number, or by is missing
- 404 not_found: the business is not yours or is in the other mode
- 422 rejected: month is not from 1 to 12, or a year has already been closed
GET/v1/businesses/{business}/years
Shows which month the financial year starts in, and every year that has been closed or reopened, oldest first.
Path
Returns
200 with starts_in_month (1 to 12) and data: years with starts_on, ends_on, status (closed or reopened), profit (income minus costs for the year, smallest currency unit), closed_by, closed_at, reopened_by, reopened_at, reopen_reason.
Errors
- 404 not_found: the business is not yours or is in the other mode
POST/v1/businesses/{business}/years/{year_end}/close
Closes the financial year ending on the given date: every month in it is closed and the year's profit is noted. Earlier years with entries must be closed first. The response also counts draft documents and unmatched bank lines left in the year, which can no longer be recorded there.
Path
business | The business id. |
year_end | Last day of the financial year, YYYY-MM-DD, e.g. 2026-12-31. |
Body
bystringrequired | Who closed the year. |
Example
{
"by": "Fatima Al-Kuwari"
}
Returns
201 with the year (starts_on, ends_on, status closed, profit, closed_by, closed_at, reopened_by, reopened_at, reopen_reason) and still_waiting with drafts and unmatched_bank_lines.
Errors
- 400 invalid_request: year_end is not YYYY-MM-DD, the body is not a JSON object, or by is missing
- 404 not_found: the business is not yours or is in the other mode
- 422 rejected: year_end is not the last day of a financial year (the message gives the right date), the year is already closed, or the year before has entries and is not closed yet
POST/v1/businesses/{business}/years/{year_end}/reopen
Reopens the latest closed financial year so a correction can be recorded; all its months open again. The reopening and its reason are logged. Close the year again when the correction is done.
Path
business | The business id. |
year_end | Last day of the closed financial year, YYYY-MM-DD. |
Body
bystringrequired | Who reopened the year. |
reasonstringrequired | Why it is reopened. |
Example
{
"by": "Fatima Al-Kuwari",
"reason": "Lulu Hypermarket invoice for December was missed"
}
Returns
200 with the year: starts_on, ends_on, status reopened, profit, closed_by, closed_at, reopened_by, reopened_at, reopen_reason.
Errors
- 400 invalid_request: year_end is not YYYY-MM-DD, the body is not a JSON object, or by or reason is missing
- 404 not_found: the business is not yours or is in the other mode
- 422 rejected: the year ending on that date isn't closed, or a later year is closed (only the latest closed year can be reopened)
AI bookkeeper
GET/v1/businesses/{business}/bookkeeper
Shows whether the AI bookkeeper is working for a business, the questions it is waiting on the owner to answer, and the latest 50 things it did. It works only when the business's plan includes it, it is not paused, and the business is not read-only.
Path
businessrequired | The business's id. |
Returns
200 with on, plan_has, paused, auto_limit; questions (open ones, oldest first: id, kind of draft or bank_line, subject_id, question_en, question_ar, asked_at, sent, options [{key, en, ar, action, account, paid_from}]); and log (newest first: id, action, subject_id, summary, at, undone, undone_by, can_undo).
Errors
- 404 not_found when the business is not yours or belongs to the other mode
POST/v1/businesses/{business}/bookkeeper/log/{entry}/undo
Undoes something the AI bookkeeper did: a recorded receipt or bill is voided, and a recorded bank line is unmatched and its entry reversed. Only log entries with action approved or recorded can be undone (can_undo is true).
Path
businessrequired | The business's id. |
entryrequired | The id of the log entry, from the log in the bookkeeper status. |
Body
bystringrequired | Who undid it. |
Example
{
"by": "Khalid Al-Thani"
}
Returns
200 with the bookkeeper status (on, plan_has, paused, auto_limit, questions) and the latest 20 log entries.
Errors
- 400 invalid_request when by is missing, or the entry is not an approval or a recorded bank line
- 404 not_found when the business is not yours or the log entry is not found
- 409 already_undone when the entry has already been undone
- 422 rejected when the books refuse to void or reverse it
POST/v1/businesses/{business}/bookkeeper/pause
Stops the AI bookkeeper working on a business until you resume it. Pausing an already paused business changes nothing.
Path
businessrequired | The business's id. |
Body
bystringrequired | Who paused it. |
Example
{
"by": "Khalid Al-Thani"
}
Returns
200 with on, plan_has, paused and auto_limit.
Errors
- 400 invalid_request when by is missing
- 404 not_found when the business is not yours or belongs to the other mode
POST/v1/businesses/{business}/bookkeeper/questions/{question}/answer
Answers one of the AI bookkeeper's open questions on the owner's behalf, by choosing one of its options. Depending on the option, the draft is recorded, the bank line is recorded (and a rule is learned so similar lines are recorded on their own next time), or the item is left as it is.
Path
businessrequired | The business's id. |
questionrequired | The question's id. |
Body
optionstringrequired | The key of one of the question's options, such as "1". A number is also accepted. |
bystringrequired | Who answered. |
Example
{
"option": "1",
"by": "Khalid Al-Thani"
}
Returns
200 with message: a short confirmation of what was done, such as the number of the document recorded.
Errors
- 400 invalid_request when option is missing or is not one of the answers given, or by is missing
- 404 not_found when the business is not yours or the question is not found
- 409 already_answered when the question has already been answered
- 409 gone when the draft or bank line the question is about is no longer waiting
- 422 rejected when the books refuse to record it
POST/v1/businesses/{business}/bookkeeper/resume
Lets the AI bookkeeper work on a business again after a pause. Send a JSON object as the body; an empty one is fine.
Path
businessrequired | The business's id. |
Example
{}
Returns
200 with on, plan_has, paused and auto_limit.
Errors
- 400 invalid_request when the body is not a JSON object
- 404 not_found when the business is not yours or belongs to the other mode
POST/v1/businesses/{business}/bookkeeper/run
Runs one pass of the AI bookkeeper straight away instead of waiting for its daily run. It records receipts and bills it is sure of, matches and records bank lines, asks the owner about the rest (at most five new questions a pass), and closes last month when nothing is left open.
Path
businessrequired | The business's id. |
Returns
200 with drafts_checked, approved, asked, held, bank_matched, bank_recorded, bank_asked, month_closed (the first day of the month closed, YYYY-MM-DD, or null) and ai_calls.
Errors
- 404 not_found when the business is not yours or belongs to the other mode
- 409 bookkeeper_off when the plan does not include the AI bookkeeper, it is paused, or the business is read-only
Accountants
GET/v1/reviewers
Lists your accountants by name, each with the ids of the businesses they have been given. Your own admins and BasePipe staff are not included.
Returns
200 with data: an array of accountants, each with id, name, email, is_active and businesses (an array of business ids).
POST/v1/reviewers
Adds an outside accountant who can review the books of the businesses you give them, on the accountant screen. Accountants belong to your partner account, not to a mode.
Body
namestringrequired | The accountant's name. |
emailstring | The accountant's email address. |
Example
{
"name": "Fatima Al-Sulaiti",
"email": "fatima@doha-audit.qa"
}
Returns
201 with id, name, email, is_active and businesses (an empty array).
Errors
- 400 invalid_request when name is missing
- 403 accountant_screen_off when the accountant screen is switched off for your partner account (switch it on in the admin screen, under Accountants)
POST/v1/reviewers/{reviewer}/businesses
Lets an accountant see and review one of your businesses. Giving the same business twice changes nothing. A test key can only give practice businesses.
Path
reviewerrequired | The accountant's id. |
Body
business_idstringrequired | The id of the business to give them. |
Example
{
"business_id": "01936f2b-1d0a-7c55-8e21-3f4a9b6c7d80"
}
Returns
201 with reviewer_id and business_id.
Errors
- 400 invalid_request when business_id is not an id
- 404 not_found when the accountant is not yours, or the business is not yours or belongs to the other mode
DELETE/v1/reviewers/{reviewer}/businesses/{business}
Stops an accountant seeing one business. It succeeds even if they did not have it.
Path
reviewerrequired | The accountant's id. |
businessrequired | The business's id. |
Returns
200 with reviewer_id, business_id and removed: true.
Errors
- 400 invalid_request when the business id is not in the right format
- 404 not_found when the accountant is not yours
POST/v1/reviewers/{reviewer}/sign-in-links
Makes a sign-in link to send to an accountant. The link works once and expires 15 minutes after it is made; it signs them in to the accountant screen for 12 hours, covering only the businesses they have been given. It does not work for an accountant who has been switched off.
Path
reviewerrequired | The accountant's id. |
Body
langstring | en or ar, the language the screen opens in. Defaults to en. |
Example
{
"lang": "ar"
}
Returns
201 with url (https://app.basepipe.io/review/sign-in?token=...) and expires_at (UTC time, 15 minutes from now).
Errors
- 400 invalid_request when lang is not en or ar
- 403 accountant_screen_off when the accountant screen is switched off for your partner account
- 404 not_found when the accountant is not yours
Plans and billing
GET/v1/billing/statement
Shows, for one month, what you collected from your businesses, BasePipe's revenue share of it, and the charge for WhatsApp messages and receipts read above each business's monthly fair-use allowance. With a test key it covers your practice businesses only.
Query
monthstring | The month, YYYY-MM. Defaults to the current month (UTC). |
Returns
200 with month, currency, businesses, on_trial, active, overdue (overdue and cancelled), collected, share_percent, share, usage_charge, owed, and lines: one per business with business_id, business, plan, state, collected, wa_messages, receipts, wa_over, receipts_over and usage_charge. share_percent and share are null until a revenue share is agreed. Amounts are in the smallest currency unit.
Errors
- 400 invalid_request when month does not look like 2026-11
GET/v1/businesses/{business}/subscription
Shows which plan a business is on, where it stands and this month's usage against its limits. A business whose trial or paid period has run out, or whose plan you cancelled, is read-only: the owner can still see and print everything, but nothing new can be recorded.
Path
businessrequired | The business's id. |
Returns
200 with state (none, trial, active, overdue or cancelled), read_only, plan ({id, name} or null), trial_ends_on, paid_until, and usage: {wa_messages, wa_limit, receipts, receipt_limit} (a null limit means no limit).
Errors
- 404 not_found when the business is not yours or belongs to the other mode
PUT/v1/businesses/{business}/subscription
Puts a business on one of your plans. A business new to plans starts the plan's free trial today; a business already on a plan just switches plan, and a cancelled one is started again. You can also move the trial's end date to give more time or end it early.
Path
businessrequired | The business's id. |
Body
plan_idstringrequired | The id of one of your active plans in the same mode as the business. |
trial_ends_onstring | Last day of the free trial, YYYY-MM-DD. |
Example
{
"plan_id": "01936f2a-7c4e-7b10-9a3d-5e8f1c2b4a60",
"trial_ends_on": "2026-12-31"
}
Returns
200 with the subscription: state, read_only, plan, trial_ends_on, paid_until and usage.
Errors
- 400 invalid_request when plan_id is not an id or trial_ends_on is not a date
- 404 not_found when the business is not yours or belongs to the other mode
- 422 rejected when the plan is not one of yours in this mode, or the plan is switched off
POST/v1/businesses/{business}/subscription/cancel
Stops a business's plan. The business becomes read-only straight away, until you put it on a plan again or record a payment.
Path
businessrequired | The business's id. |
Returns
200 with the subscription, now with state cancelled and read_only true.
Errors
- 404 not_found when the business is not yours or belongs to the other mode
- 422 rejected when the business has no running plan
POST/v1/businesses/{business}/subscription/payments
Records that a business paid you for its plan, and until when that payment covers it. The business is paid up to the latest covers_until you have recorded, and a cancelled plan starts running again. The amount is in the plan's currency and counts towards that month's billing statement.
Path
businessrequired | The business's id. |
Body
amountintegerrequired | What was paid, in the smallest currency unit, above zero (99 QAR is 9900). |
covers_untilstringrequired | Last day the payment covers, YYYY-MM-DD. Not before paid_on. |
paid_onstring | When it was paid, YYYY-MM-DD. Defaults to today (UTC). |
referencestring | Your own reference, such as a receipt or transfer number. |
recorded_bystringrequired | Who recorded the payment. |
Example
{
"amount": 9900,
"paid_on": "2026-11-16",
"covers_until": "2026-12-15",
"reference": "QNB-TRF-448812",
"recorded_by": "Mariam Al-Kuwari"
}
Returns
201 with the subscription: state, read_only, plan, trial_ends_on, paid_until and usage.
Errors
- 400 invalid_request when amount is not a whole number above zero, paid_on or covers_until is not a date, or recorded_by is missing
- 404 not_found when the business is not yours or belongs to the other mode
- 422 rejected when the business is not on a plan yet, or covers_until is before paid_on
GET/v1/plans
Lists the plans you sell to your businesses, active plans first and then by price. A test key sees only its practice plans; a live key sees only live plans.
Returns
200 with data: an array of plans, each with id, name, name_ar, price, currency, period, trial_days, wa_limit, receipt_limit, is_default, is_active, ai_bookkeeper, ai_auto_limit and created_at.
POST/v1/plans
Creates a plan with your own price, billing period, free trial and optional monthly limits. BasePipe never charges your businesses; you collect the money and record payments. Marking a plan as the default makes new businesses start on it, and takes the default away from your other plans.
Body
namestringrequired | The plan's name. Must be unique among your active plans. |
name_arstring | The plan's name in Arabic. |
priceintegerrequired | The price in the smallest currency unit, zero or more (99 QAR is 9900). |
currencystring | Three-letter currency code. Defaults to QAR. |
periodstring | month or year. Defaults to month. |
trial_daysinteger | Length of the free trial, 0 to 90 days. Defaults to 14. |
wa_limitinteger | Most WhatsApp messages a month, 1 to 1000000. Leave out for no limit. During a trial BasePipe's own trial limit (150) also applies. |
receipt_limitinteger | Most receipts read a month, 1 to 1000000. Leave out for no limit. During a trial BasePipe's own trial limit (30) also applies. |
is_defaultboolean | New businesses start on this plan and its trial. Defaults to false. |
ai_bookkeeperboolean | Whether the plan includes the AI bookkeeper. Defaults to false. |
ai_auto_limitinteger | The largest receipt or bill the AI bookkeeper may record on its own, in the smallest currency unit. Defaults to 100000 (1,000 QAR). |
Example
{
"name": "Dukkan Monthly",
"name_ar": "دكان شهري",
"price": 9900,
"currency": "QAR",
"period": "month",
"trial_days": 14,
"wa_limit": 400,
"receipt_limit": 100,
"is_default": true,
"ai_bookkeeper": true,
"ai_auto_limit": 50000
}
Returns
201 with the new plan: id, name, name_ar, price, currency, period, trial_days, wa_limit, receipt_limit, is_default, is_active, ai_bookkeeper, ai_auto_limit, created_at.
Errors
- 400 invalid_request when name is missing, price is not a whole number of zero or more, period is not month or year, currency is not three letters, trial_days is outside 0 to 90, wa_limit or receipt_limit is outside 1 to 1000000, or ai_auto_limit is not a whole number of zero or more
- 409 conflict when you already have an active plan with that name
PUT/v1/plans/{plan}
Replaces every setting of a plan, so send all the fields you would send to create it; anything left out goes back to its default. Send is_active false to switch a plan off: businesses already on it keep it, but no business can be newly put on it, and a switched-off plan is never the default.
Path
planrequired | The plan's id. |
Body
namestringrequired | The plan's name. |
name_arstring | The plan's name in Arabic. |
priceintegerrequired | The price in the smallest currency unit (99 QAR is 9900). |
currencystring | Three-letter currency code. Defaults to QAR. |
periodstring | month or year. Defaults to month. |
trial_daysinteger | 0 to 90. Defaults to 14. |
wa_limitinteger | WhatsApp messages a month, 1 to 1000000, or leave out for no limit. |
receipt_limitinteger | Receipts read a month, 1 to 1000000, or leave out for no limit. |
is_defaultboolean | Make this the plan new businesses start on. Ignored when is_active is false. |
is_activeboolean | false switches the plan off. Defaults to true. |
ai_bookkeeperboolean | Whether the plan includes the AI bookkeeper. Defaults to false. |
ai_auto_limitinteger | The largest receipt or bill the AI bookkeeper may record on its own. Defaults to 100000. |
Example
{
"name": "Dukkan Monthly",
"name_ar": "دكان شهري",
"price": 12900,
"currency": "QAR",
"period": "month",
"trial_days": 30,
"wa_limit": 500,
"receipt_limit": 150,
"is_default": true,
"is_active": true,
"ai_bookkeeper": true,
"ai_auto_limit": 75000
}
Returns
200 with the updated plan, in the same shape as when it was created.
Errors
- 400 invalid_request when a field fails the same checks as when creating a plan
- 404 not_found when the plan is not one of yours in this mode
- 409 conflict when another active plan already has that name
WhatsApp
GET/v1/businesses/{business}/whatsapp-owners
Lists the phones linked to a business, oldest first.
Path
businessrequired | The business's id. |
Returns
200 with data: an array of owners, each with id, phone, name, lang and is_active.
Errors
- 404 not_found when the business is not yours or belongs to the other mode
POST/v1/businesses/{business}/whatsapp-owners
Links an owner's phone to a business, so messages from that phone to your WhatsApp number are kept in that business's books. A phone can belong to only one of your businesses.
Path
businessrequired | The business's id. |
Body
phonestringrequired | The owner's full international number, like +97455500000. Spaces are removed. |
namestring | The owner's name. |
langstring | en or ar, the language replies are sent in. Defaults to ar. |
Example
{
"phone": "+97455512345",
"name": "Hamad Al-Marri",
"lang": "ar"
}
Returns
201 with id, phone, name, lang and is_active.
Errors
- 400 invalid_request when phone is missing or not a full international number, or lang is not en or ar
- 404 not_found when the business is not yours or belongs to the other mode
- 409 conflict when that phone is already linked to one of your businesses
GET/v1/whatsapp-numbers
Lists your WhatsApp numbers, oldest first.
Returns
200 with data: an array of numbers, each with id, number, label and is_active.
POST/v1/whatsapp-numbers
Adds a WhatsApp number of yours, set up on Twilio, that owners message to keep their books. Messages to the number tell BasePipe which partner they are for. Numbers belong to your partner account, not to a mode.
Body
numberstringrequired | The full international number, like +97444001234. Spaces are removed. |
labelstring | A name for the number, for your own use. |
twilio_account_sidstring | The Twilio account the number is on. |
Example
{
"number": "+97444001234",
"label": "SouqPay Books main line",
"twilio_account_sid": "AC0123456789abcdef0123456789abcdef"
}
Returns
201 with id, number, label and is_active.
Errors
- 400 invalid_request when number is missing or is not a full international number
- 409 conflict when that number is already set up
GET/v1/whatsapp-templates
Lists the WhatsApp templates you have set, by kind and language.
Returns
200 with data: an array of templates, each with kind, lang and content_sid.
POST/v1/whatsapp-templates
Sets the approved Twilio message template used for one kind of message in one language, so it can be sent outside WhatsApp's 24-hour reply window. For now only the evening sales check-in can use a template. Setting the same kind and language again replaces the template.
Body
kindstringrequired | The kind of message. Must be sales_checkin. |
langstring | en or ar. Defaults to ar. |
content_sidstringrequired | The Twilio content id: HX followed by 32 lowercase letters and numbers. |
Example
{
"kind": "sales_checkin",
"lang": "ar",
"content_sid": "HX4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c"
}
Returns
201 with kind, lang and content_sid.
Errors
- 400 invalid_request when kind is not sales_checkin, lang is not en or ar, or content_sid is missing or not a Twilio content id
Background jobs
GET/v1/businesses/{business}/jobs
Lists the background work run for a business, newest first, such as monthly wear and tear, applying bank rules, invoice reminders, the weekly summary, recurring documents and the daily sales question. Use it when something you expected didn't happen.
Path
Query
limitinteger | How many to return, 1 to 200. Defaults to 50. |
Returns
200 with data: jobs with id, kind (e.g. wear_and_tear, apply_rules, invoice_reminders, weekly_summary, recurring, schedules, sales_checkin, bookkeeper), status (queued, running, done or failed), attempts, last_error, result, run_at, created_at, finished_at.
Errors
- 404 not_found: the business is not yours or is in the other mode
GET/v1/businesses/{business}/outbox
Lists the messages prepared for one business's owner, newest first. Without status it lists all of them, whatever their status.
Path
Query
statusstring | pending, sent or cancelled. Leave out for all. |
limitinteger | How many to return, 1 to 200. Defaults to 50. |
Returns
200 with data: messages with id, business_id, kind, audience, body_en, body_ar, data, status, created_at, sent_at, sent_via.
Errors
- 400 invalid_request: status is not pending, sent or cancelled
- 404 not_found: the business is not yours or is in the other mode
GET/v1/outbox
Lists messages BasePipe has prepared for owners across all your businesses in the key's mode, oldest first: invoice reminders, the weekly summary and the evening daily sales question. Deliver each one yourself, for example on WhatsApp, then mark it sent.
Query
statusstring | pending, sent or cancelled. Defaults to pending. |
limitinteger | How many to return, 1 to 200. Defaults to 50. |
Returns
200 with data: messages with id, business_id, kind (e.g. invoice_reminder, weekly_summary, sales_checkin), audience, body_en, body_ar, data (details such as the date), status, created_at, sent_at, sent_via.
Errors
- 400 invalid_request: status is not pending, sent or cancelled
POST/v1/outbox/{message}/sent
Tells BasePipe you have delivered a waiting message, so it is not listed as pending again. Only pending messages can be marked.
Path
message | The message id from the outbox. |
Body
viastringrequired | How it was delivered, e.g. whatsapp or sms. |
Example
{
"via": "whatsapp"
}
Returns
200 with the message, now with status sent, sent_at and sent_via.
Errors
- 400 invalid_request: the body is not a JSON object, or via is missing
- 404 not_found: the id is not a valid id, or no pending message with this id belongs to your partner account
- 404 not_found: the message belongs to the other mode (a test key marking a live message, or the other way round).