# BillOS API

> Israeli tax documents and bookkeeping, as a JSON HTTP API. Legally valid Israeli tax documents with gapless numbering, digital signatures, an immutable audit trail and the regulatory מבנה אחיד export. Registered with the Israel Tax Authority software registry.

Append `.md` to any URL below for its markdown source. The whole documentation as a single file: https://docs.billos.co.il/llms-full.txt. OpenAPI 3.1 spec: https://docs.billos.co.il/openapi.json

## Guides

- [Overview](https://docs.billos.co.il/overview.md)
- [Quickstart: invoice a customer in five calls](https://docs.billos.co.il/quickstart.md)
- [Authentication](https://docs.billos.co.il/authentication.md)
- [Sandbox: test keys](https://docs.billos.co.il/sandbox.md)
- [Conventions](https://docs.billos.co.il/conventions.md)
- [The document lifecycle](https://docs.billos.co.il/document-lifecycle.md)
- [Businesses](https://docs.billos.co.il/businesses.md)
- [Documents](https://docs.billos.co.il/documents.md)
- [Expenses (ספר תקבולים ותשלומים)](https://docs.billos.co.il/expenses.md)
- [Webhooks](https://docs.billos.co.il/webhooks.md)
- [MCP: BillOS for AI agents](https://docs.billos.co.il/mcp.md)
- [CLI: BillOS from the terminal](https://docs.billos.co.il/cli.md)
- [Regulatory outputs](https://docs.billos.co.il/regulatory-outputs.md)

## Businesses

One business per end user. Every other path is nested under its id.

- [List your businesses](https://docs.billos.co.il/reference/listBusinesses.md): `GET /businesses`: Every business created under your key, newest first. Signing-key material is never included.
- [Create a business](https://docs.billos.co.il/reference/createBusiness.md): `POST /businesses`: One business per end user. Everything else is nested under the id this returns.
- [Read a business](https://docs.billos.co.il/reference/getBusiness.md): `GET /businesses/{bid}`: Read a business
- [Update a business](https://docs.billos.co.il/reference/updateBusiness.md): `PATCH /businesses/{bid}`: Profile, branding and `requireAllocation`. The tax id and dealer type of a business that has already issued documents are not editable.
- [Deactivate a business](https://docs.billos.co.il/reference/deactivateBusiness.md): `POST /businesses/{bid}/deactivate`: Your own pause switch on a tenant. A deactivated business keeps its data and its reads, but every write (drafts, issuing, expenses, uploads) is refused until you reactivate it. Distinct from `approvalStatus`, which only BillOS sets. Idempotent.
- [Reactivate a business](https://docs.billos.co.il/reference/reactivateBusiness.md): `POST /businesses/{bid}/reactivate`: Clears a deactivation you set. Reactivating never grants anything `approvalStatus` does not: if BillOS suspended the account, writes stay refused. Idempotent.
- [List your API keys](https://docs.billos.co.il/reference/listKeys.md): `GET /keys`: Every key under your client: the one you are using and any others, live or revoked. Keys are minted and revoked by us (the Authentication guide explains rotation); this is how you see that a key you did not ask for exists.
- [Your API usage](https://docs.billos.co.il/reference/getUsage.md): `GET /usage`: Your key's own request rollups per endpoint: requests and error counts over the window. Days are Asia/Jerusalem calendar days.

## Parties

Saved customers. Optional: a document may carry an inline party instead.

- [List parties](https://docs.billos.co.il/reference/listParties.md): `GET /businesses/{bid}/parties`: List parties
- [Create a party](https://docs.billos.co.il/reference/createParty.md): `POST /businesses/{bid}/parties`: Create a party
- [Update a party](https://docs.billos.co.il/reference/updateParty.md): `PATCH /businesses/{bid}/parties/{id}`: Update a party
- [Record digital-document consent](https://docs.billos.co.il/reference/recordPartyConsent.md): `POST /businesses/{bid}/parties/{id}/consent`: Stamps the party as having consented to receiving documents digitally (מסמכים ממוחשבים) rather than on paper. Required before you deliver a document by link or email.
- [Find a party or create it](https://docs.billos.co.il/reference/findOrCreateParty.md): `POST /businesses/{bid}/parties/find-or-create`: Matches an existing party by phone (last nine digits) and then by exact name; creates one otherwise. 201 when created, 200 when found; `created` says which.

## Documents

The tax documents themselves: draft, issue, correct, print.

- [List documents](https://docs.billos.co.il/reference/listDocuments.md): `GET /businesses/{bid}/documents`: List documents
- [Create a draft](https://docs.billos.co.il/reference/createDocument.md): `POST /businesses/{bid}/documents`: A draft is a קובץ זמני, not a tax document: no number is consumed and any rendering of it is watermarked "טיוטה". Patch and delete it freely until you issue.
- [Read a document](https://docs.billos.co.il/reference/getDocument.md): `GET /businesses/{bid}/documents/{id}`: Read a document
- [Update a draft](https://docs.billos.co.il/reference/updateDocument.md): `PATCH /businesses/{bid}/documents/{id}`: Drafts only. An issued document answers `409 not_draft`; it is immutable at the database engine.
- [Delete a draft](https://docs.billos.co.il/reference/deleteDocument.md): `DELETE /businesses/{bid}/documents/{id}`: Drafts only. Issued documents are corrected with a credit note, never deleted.
- [Issue a document](https://docs.billos.co.il/reference/issueDocument.md): `POST /businesses/{bid}/documents/{id}/issue`: The point of no return. Assigns the next gapless number, freezes a full snapshot, renders the PDF and signs it.
- [Correct with a credit note](https://docs.billos.co.il/reference/issueCreditNote.md): `POST /businesses/{bid}/documents/{id}/credit-note`: The only way to undo an issued 305 or 320: issues a linked חשבונית מס זיכוי (330) mirroring the original amounts. For a receipt (400) it issues a negative receipt. Nothing is ever deleted (הוראה 23).
- [Preview a draft as PDF](https://docs.billos.co.il/reference/previewDocument.md): `POST /businesses/{bid}/documents/{id}/preview`: The draft rendered as a "טיוטה"-watermarked PDF so your user sees exactly what they are about to issue. Nothing is recorded and no number is consumed. Drafts only.
- [Download the PDF](https://docs.billos.co.il/reference/printDocument.md): `POST /businesses/{bid}/documents/{id}/prints`: Israeli law delivers the origin (מקור) exactly once, per הוראה 18(ב)2. `auto` is what a download button should send: it serves the origin on the first ever print and a copy forever after, so a repeat click never errors, and the `X-Print-Variant` header tells you which one you got.
- [Get the public PDF link](https://docs.billos.co.il/reference/shareDocument.md): `POST /businesses/{bid}/documents/{id}/share`: The no-login link to the same PDF `prints` serves, for a WhatsApp or email hand-off: the host streams it at `path` (`/api/docs/<slug>/d.pdf`). It IS a print: `auto` hands out the origin exactly once and the copy after that (הוראה 18(ב)2), so `variant` says which one the link carries.
- [Email the document link](https://docs.billos.co.il/reference/emailDocument.md): `POST /businesses/{bid}/documents/{id}/email`: Sends the public PDF link to up to 5 addresses in a BillOS-branded email, one email per address. Sending IS a print (`auto`): the origin exactly once, the copy after (הוראה 18(ב)2). Issued (or cancelled) documents only; not available in sandbox; rate-limited (BOOKS_EMAIL_RATE_PER_MIN, default 10/min).

## Expenses

The purchase side of the ledger, including receipt OCR.

- [List expenses](https://docs.billos.co.il/reference/listExpenses.md): `GET /businesses/{bid}/expenses`: List expenses
- [Create an expense](https://docs.billos.co.il/reference/createExpense.md): `POST /businesses/{bid}/expenses`: Opens a draft, or records in one call when the body is complete. `amountIncVat` is the GROSS (Israeli prices include VAT) and `vatAmount` is the portion inside it. Never add the two.
- [Create and record in one call](https://docs.billos.co.il/reference/recordExpenseDirect.md): `POST /businesses/{bid}/expenses/record`: A complete receipt in hand and no draft to keep: the same `input` the record step takes, recorded in one round-trip. Idempotent on the key.
- [Read an expense](https://docs.billos.co.il/reference/getExpense.md): `GET /businesses/{bid}/expenses/{id}`: Includes the raw OCR extraction when the row came from a scan.
- [Update a draft expense](https://docs.billos.co.il/reference/updateExpense.md): `PATCH /businesses/{bid}/expenses/{id}`: Update a draft expense
- [Discard a draft](https://docs.billos.co.il/reference/deleteExpenseDraft.md): `DELETE /businesses/{bid}/expenses/{id}`: A draft is yours to discard. A recorded expense is a ledger entry and can only be corrected (storno), so this answers 404.
- [Record an expense](https://docs.billos.co.il/reference/recordExpense.md): `POST /businesses/{bid}/expenses/{id}/record`: Writes the immutable ledger row. A non-ILS expense without `amountIls` is refused: the ledger sums agorot without looking at currency, and the row cannot be edited afterwards.
- [Correct with a storno](https://docs.billos.co.il/reference/correctExpense.md): `POST /businesses/{bid}/expenses/{id}/correction`: A recorded expense is immutable; a correction writes a reversing row (הוראה 23). Pass `redraft: true` to also open a fresh DRAFT carrying the same fields and a copy of the receipt file: fix it and record again. The storno stands even if the draft fails.
- [Open a draft from a receipt photo](https://docs.billos.co.il/reference/ocrExpense.md): `POST /businesses/{bid}/expenses/ocr`: POST the raw image or PDF bytes with the matching `Content-Type`. A vision model reads the receipt and opens a draft expense from what it found; your user confirms and records.

## Exports & Reports

מבנה אחיד, continuity, management reports, backups, file downloads.

- [Generate a מבנה אחיד export](https://docs.billos.co.il/reference/exportOpenfrmt.md): `POST /businesses/{bid}/exports/openfrmt`: The regulatory filing artifact (OPENFRMT v1.31): one zip holding INI.TXT and BKMVDATA.TXT under the exact directory tree the spec mandates. This is what an accountant or an auditor asks for. Download the zip through `GET /files/{id}`.
- [Numbering-continuity report](https://docs.billos.co.il/reference/continuityReport.md): `GET /businesses/{bid}/reports/continuity`: Gap check per document type: the evidence that numbering is unbroken.
- [Management report](https://docs.billos.co.il/reference/managementReport.md): `GET /businesses/{bid}/reports/{kind}`: Cash-basis, mirroring the OPENFRMT semantics exactly: income is payment-bearing documents, expenses count at record. Default is a rendered Hebrew PDF carrying the business branding; `?format=json` returns the aggregates for your own dashboard. The `profit` report includes a VAT block (עסקאות / תשומות / נטו) for VAT-registered dealers.
- [Initiated backup](https://docs.billos.co.il/reference/createBackup.md): `POST /businesses/{bid}/backup`: The גיבוי יזום the regulations require: an archive of the ledger rows, with the full file index and each blob sha256, so the blob store can be audited against it.
- [Batched receipt thumbnails](https://docs.billos.co.il/reference/fileThumbnails.md): `POST /businesses/{bid}/files/thumbs`: Small data-URI JPEG previews for up to 60 stored image files in ONE call, built for list views, where a request per row would burn the rate limit. Non-image files (PDFs) are simply absent from the answer.
- [Download a file](https://docs.billos.co.il/reference/getFile.md): `GET /businesses/{bid}/files/{id}`: Streams the stored bytes: export zips, backups, receipts. Issued document PDFs are served by `prints` instead, so the once-only origin rule is enforced.

## Webhooks

Events pushed to your URL: the trigger side of Make/Zapier-style automations. Signed, retried with backoff, testable.

- [List webhook endpoints](https://docs.billos.co.il/reference/listWebhooks.md): `GET /webhooks`: List webhook endpoints
- [Create a webhook endpoint](https://docs.billos.co.il/reference/createWebhook.md): `POST /webhooks`: BillOS POSTs subscribed events to `url` as they happen: signed (HMAC-SHA256), retried with backoff, at-least-once. The full envelope, verification code and retry schedule are in the Webhooks guide.
- [Update a webhook endpoint](https://docs.billos.co.il/reference/updateWebhook.md): `PATCH /webhooks/{id}`: `{"active": true}` also re-arms an endpoint that was auto-disabled after sustained failure.
- [Delete a webhook endpoint](https://docs.billos.co.il/reference/deleteWebhook.md): `DELETE /webhooks/{id}`: Removes the endpoint and its delivery history.
- [List recent deliveries](https://docs.billos.co.il/reference/listWebhookDeliveries.md): `GET /webhooks/{id}/deliveries`: Newest first, the debugging view: what was sent, when, and what your endpoint answered.
- [Send a test event now](https://docs.billos.co.il/reference/testWebhook.md): `POST /webhooks/{id}/test`: Delivers one synthetic `webhook.test` event immediately, regardless of the endpoint's event filter: how you wire up a Make/Zapier trigger without issuing anything. `delivered` says whether your endpoint answered 2xx.