מסמכים
רשימת מסמכים, פרטי מסמך והקובץ המקורי.
קוראים, מעלים, מתייגים ומייצאים את המסמכים הפיננסיים של החשבון, ישירות מהקוד שלכם. JSON נקי על גבי HTTPS, עם מפתח לכל חשבון.
curl https://app.doxbox.io/api/v1/documents?limit=1 \
-H "Authorization: Bearer DOXBOX_API_KEY"
{
"data": [
{
"id": 1042,
"documentNumber": "INV-2026-118",
"documentDate": "2026-07-16",
"totalAmount": 1170.0,
"currency": "ILS",
"supplierName": "Acme Ltd"
}
],
"nextCursor": 1041
}
רשימת מסמכים, פרטי מסמך והקובץ המקורי.
שולחים מסמך חדש, והוא נסרק כמו כל מסמך אחר.
מוסיפים ומסירים תגיות ממסמכים.
רשימת ספקים ויצירת קובצי ייצוא.
מנהל החשבון יוצר מפתח באפליקציית הווב, במחשב: Settings → API & integrations → Create key. המפתח מוצג פעם אחת בלבד.
מוסיפים את המפתח לכותרת Authorization כ-Bearer ומבקשים את רשימת המסמכים. מפתח רגיל הוא לקריאה בלבד; להעלאה ולתיוג צריך מפתח write.
התשובה חוזרת עם המסמכים ועם nextCursor לעמוד הבא.
כל מה שיש היום ב-rest.doxbox.io, באותו סדר: מדריך, 12 נקודות קצה, חיבור ל-Claude ומתכונים. התיעוד הטכני נשאר באנגלית.
The DoxBox API gives your account programmatic access to its financial documents: list and read invoices and receipts, fetch the original files, list suppliers, read and set document tags, generate exports, and upload new documents. Everything is JSON over HTTPS, scoped to a single account.
| Setting | Value |
|---|---|
| Base URL | https://app.doxbox.io |
| Base path | /api/v1 |
| Format | JSON, UTF-8 |
| Access | Read by default; uploading and changing tags require a write key |
Prefer to ask in plain language? Add DoxBox as a connector in claude.ai with your DoxBox user, or run the official MCP server locally in Claude Code, Claude Desktop and Cursor with an API key.
From zero to your first authenticated response in under a minute.
1. Create a key. As an account admin, in the DoxBox web app on desktop: Settings → API & integrations → Create key. Copy it, it is shown only once.
2. Export it in your shell, then make the call. The reference shows every request in curl, JavaScript and Python.
# set once export DOXBOX_API_KEY="dbx_..." curl https://app.doxbox.io/api/v1/documents \ -H "Authorization: Bearer $DOXBOX_API_KEY"
A per-account API key, sent as a Bearer token on every request except /health.
Authorization: Bearer dbx_<prefix>_<secret>
Shown once. The full key appears only at creation, and DoxBox stores just a hash. Lost it? Revoke and create a new one. Revocation takes effect immediately, and a key can only ever touch its own account data.
Keys are managed in Settings → API & integrations. The same screen lists your keys (created, last used) and lets you revoke one.
Every key carries one of two permission levels, chosen at creation. Calling a write endpoint with a read key returns 403 API_KEY_FORBIDDEN.
| Scope | Grants |
|---|---|
| read | Read documents, suppliers and tags, generate exports (default) |
| write | Everything in read, plus uploading documents and changing document tags |
The handful of rules that hold across every endpoint.
List endpoints use cursor pagination: ?limit= (1 to 100, default 25) and ?cursor= (the last id from the previous page). Responses carry nextCursor: an id, or null on the last page.
Requests are limited per key, 120 per minute by default. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429 with a Retry-After header.
Uploads count against your plan's monthly document limit. At the limit, POST /documents returns 403 PLAN_LIMIT_EXCEEDED and no file in the batch is ingested: all or nothing, so you are never left with a partial upload.
Uploads are de-duplicated by file content. Re-uploading a file DoxBox already has does not create a second document: the response marks it duplicate and returns the existing id. Uploads are safe to retry.
A JSON body with a human message and, where useful, a machine-readable code.
{ "message": "API key has expired", "code": "API_KEY_EXPIRED" }| HTTP | code | Meaning |
|---|---|---|
| 400 | - | Invalid request (bad parameters or body) |
| 400 | TAG_LIMIT_PER_DOCUMENT | Document already has 10 tags |
| 401 | API_KEY_MISSING | No Authorization: Bearer header |
| 401 | API_KEY_INVALID | Unknown key |
| 401 | API_KEY_REVOKED | Key was revoked |
| 401 | API_KEY_EXPIRED | Key is past its expiry |
| 403 | API_KEY_FORBIDDEN | Key lacks the required scope (for example write) |
| 403 | PLAN_LIMIT_EXCEEDED | Monthly document quota reached |
| 404 | - | Not found, or not in your account |
| 404 | TAG_NOT_FOUND | Tag not found, or not in your account |
| 429 | RATE_LIMITED | Rate limit exceeded (see Retry-After) |
Enumerated values you will see in responses. Amount fields are numbers in the document currency. Dates are ISO 8601 strings, and may be null when DoxBox could not read them from the document.
| Field | Values |
|---|---|
| documentType | Invoice · Receipt · InvoiceReceipt · CreditInvoice · TransactionAccount · Other |
| paymentStatus | Paid · Unpaid |
| currency | ILS · USD · EUR · GBP · JPY · AUD |
| tag color | teal · salmon · green · violet · sand · slate |
| tag source | manual (a person) · rule (a supplier rule) · suggested_accepted · auto |
Fields marked (detail) appear only on GET /documents/{id}; the list returns a lighter subset.
| Field | Type | Notes |
|---|---|---|
| id | number | Stable document id. |
| documentNumber | string | null | Invoice or receipt number, as read from the document. |
| documentType | enum | See the values above. |
| documentDate | ISO date | null | Date on the document. |
| poNumber (detail) | string | null | Purchase-order number. |
| netAmount · vat · vatRate · totalAmount | number | null | Amounts in currency; vatRate is a percentage. |
| currency | enum | ILS · USD · EUR · GBP · JPY · AUD. |
| paymentStatus | enum | Paid · Unpaid. |
| paymentDate (detail) | ISO date | null | When it was marked paid. |
| description (detail) | string | null | Free-text note. |
| uploadedAt (detail) | ISO datetime | When it was added to DoxBox. |
| supplierName / supplier (detail) | string / object | The list returns the name; the detail endpoint returns { id, name, crn }. |
| tags | array | [{ id, name, color, source }], in the order they were added. |
| images (detail) | array | Page image ids [{ id }], fetched via /documents/{id}/file?image=. |
Twelve endpoints under /api/v1. Every one except /health needs the key.
Service health and version. The one endpoint that needs no key, handy for uptime checks.
List the account's documents, newest first. Cursor-paginated with limit and cursor.
| Query | Type | Notes |
|---|---|---|
| limit | integer | 1 to 100, default 25 |
| cursor | integer | The last document id from the previous page |
| tags | string | Comma-separated tag ids, for example 7,12. Only documents carrying every listed tag (AND). Ids come from GET /tags. |
A single document with full metadata and the ids of its image pages. A document that is not in your account returns 404, with no cross-account existence leak.
Returns a 302 redirect to a fresh, short-lived signed URL for the document file, so the storage bucket stays private. Optional ?image=<id> selects a specific page (defaults to the first).
Upload one or more documents as multipart/form-data, in the files field. They run through the same pipeline as documents added in the app (OCR, supplier matching, de-duplication) and appear tagged as uploaded via the API.
Per-file status is created, duplicate or failed. A failed file carries a reason and never stops the rest of the batch.
The account tags (the labels a business puts on its documents), with how many documents carry each.
Replace the document's whole tag list. Send every tag id the document should carry; tags left out are removed.
The document and every tag must belong to your account (404 otherwise). A document carries at most 10 tags. Tags are created in the DoxBox app; the API attaches existing ones.
| Body | Type | Notes |
|---|---|---|
| tagIds | number[] | The full list, at most 10 ids. [] removes every tag. |
Add one tag to the document. If the document already carries it, nothing changes.
The document and every tag must belong to your account (404 otherwise). A document carries at most 10 tags. Tags are created in the DoxBox app; the API attaches existing ones.
| Body | Type | Notes |
|---|---|---|
| tagId | number | An id from GET /tags |
Remove one tag from the document.
The document and every tag must belong to your account (404 otherwise). A document carries at most 10 tags. Tags are created in the DoxBox app; the API attaches existing ones.
The account suppliers (those with documents), with per-supplier aggregates, sorted by total amount.
The businesses a connector (user) token covers: { data: [{ id, name, crn, role, canWrite, isDefault }] }. Answers 403 when called with an API key: it is for connector tokens only (MCP).
Generate an export file for a month of documents. Returns fileUrl, a signed download URL valid for about 12 hours. Exporting via the API never changes your documents.
| Field | Type | Notes |
|---|---|---|
| exportType | string | excel_monthly · csv · pdf_merged · zip |
| scope | string | all_results (default) or selected |
| selectedDocumentIds | number[] | Required when scope is selected |
| filters.year | number | For example 2026 |
| filters.month | number | 1 to 12 |
Use the API in plain language: as a connector in claude.ai, or through the local MCP server in Claude Code, Claude Desktop and Cursor. An assistant gets this API as a set of tools, so you can ask things like "which invoices from September are still unpaid?".
| Remote connector | Local server | |
|---|---|---|
| For | claude.ai (web, desktop and mobile), Claude Code, and any MCP client that supports remote servers with OAuth | Claude Code, Claude Desktop, Cursor and other local MCP clients |
| Address | https://app.doxbox.io/api/mcp | doxbox-mcp on npm (open source, MIT) |
| Sign-in | Your DoxBox user: every business you choose to include, with a permission per business | One API key = one account |
| Install | Nothing | Nothing (npx), Node 18 or newer |
| Uploading files | No | Yes |
In claude.ai go to Settings → Connectors → Add custom connector, name it DoxBox and paste the address. Sign in to DoxBox, choose which businesses to include and the permission for each one, and approve. Manage the connection in DoxBox under User settings → Connected apps. The connector is a standard OAuth 2.1 authorization server (dynamic client registration, PKCE required); access tokens last 30 days.
Run doxbox-mcp from npm with an account API key. It talks only to app.doxbox.io and keeps no data of its own. A read-only key covers searching, reading and exporting; create a Read & write key if you want the assistant to tag or upload documents. DOXBOX_BASE_URL is optional and defaults to https://app.doxbox.io.
| Tool | What it does | Needs |
|---|---|---|
| doxbox_health | API status and which server the MCP points at | none |
| doxbox_list_businesses | Remote connector only: the businesses in the connection, with the role, permission and default | read |
| doxbox_list_documents | A page of documents, newest first (limit, cursor, tag_ids) | read |
| doxbox_search_documents | Documents by supplier, date range, payment status, type, amount or tags | read |
| doxbox_get_document | One document: amounts, VAT, supplier with CRN, dates, tags, page ids | read |
| doxbox_get_document_file_url | Short-lived signed URL for the original file | read |
| doxbox_list_suppliers | Suppliers with document counts and totals, optional name filter | read |
| doxbox_list_tags | The account tags with document counts | read |
| doxbox_create_export | Excel, CSV, merged PDF or ZIP of a month, as a download link | read |
| doxbox_set_document_tags | Replace the tags of a document | write |
| doxbox_add_document_tag | Add one tag to a document | write |
| doxbox_remove_document_tag | Remove one tag from a document | write |
| doxbox_upload_documents | Local server only: upload local PDF or image files | write |
| Recipe | What it shows |
|---|---|
| Page through all documents | Follow nextCursor until it returns null. |
| Automated monthly Excel export | Call POST /exports with excel_monthly for the month, then download fileUrl. |
Try it in SwaggerBreaking changes ship under a new version, announced in advance.