Proposals
Ask Trabalance to draft a document, then approve it — the same producer a person uses, never a direct posting.
A proposal is a request to run one of Trabalance's own producers. Your app describes what it wants; a person in the business approves it; approval posts the document exactly as if they had keyed it in. Nothing an app proposes reaches the books on its own.
Mint a key with the Proposals option (Settings → API keys). The option is not a licence to post: every call is still checked against the key's own scopes and the live rights of the person the key belongs to.
What may be proposed
curl https://api.trabalance.com/api/v1/proposals/kinds -H "Authorization: Bearer tk_live_…"| Kind | Posts | Needs |
|---|---|---|
| draft_invoice | An invoice | sales_invoices (create) |
| draft_bill | A supplier bill — priced from the item cost, not your selling rate | purchases_bills (create) |
| record_receipt | A customer receipt, allocated by settlement order | sales_receipts (create) |
| record_payment | A payment to a supplier, allocated by settlement order | purchases_payments (create) |
| import_order | An invoice from a connected store order | sales_invoices (create) |
| classify_bank_lines | Categorisations for uncategorised statement lines | finance_banking (create) |
| chase_overdue · month_close · watch_risks · cash_outlook | Nothing — these are reviews you sign | a read right |
Propose, then decide
# 1. propose — nothing is posted
curl -X POST https://api.trabalance.com/api/v1/proposals \
-H "Authorization: Bearer tk_live_…" -H "Content-Type: application/json" \
-d '{"kind":"draft_invoice","input":{"customer":"<id>","lines":[{"item":"<id>","qty":2,"rate":50}]}}'
# 2. read it back — the exact payload and the evidence behind it
curl https://api.trabalance.com/api/v1/proposals/<id> -H "Authorization: Bearer tk_live_…"
# 3. approve — this is what posts, through the ordinary producer
curl -X POST https://api.trabalance.com/api/v1/proposals/<id>/approve \
-H "Authorization: Bearer tk_live_…" -H "Content-Type: application/json" -d '{"note":"ok"}'Free text works too — {"kind":"draft_bill","input":{"text":"Bill from Acme for 3 widgets at 50"}} — and a document your users upload can be proposed with {"intake_job_id":"…"}.
If the business runs an approval workflow on that document type, the proposal says so before you approve it, and posting still routes to their approvers. An approve that answers applied has posted; one that answers approved is on its way.
Listening
Subscribe a webhook to proposal.created and proposal.applied to follow the decision without polling.
Errors you should expect
| Status | Meaning |
|---|---|
| 400 | The kind is unknown, or the input is missing a field — the message names it |
| 403 | The key or its user does not hold the right this kind needs |
| 404 | No such proposal in this business |
| 409 | Already decided, or the upload has already been used |
| 422 | Trabalance will not guess: an unmatched party, a line that is not in the catalogue, or more money than the party has open |