API למפתחים

DoxBox למפתחים

קוראים, מעלים, מתייגים ומייצאים את המסמכים הפיננסיים של החשבון, ישירות מהקוד שלכם. 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
}

מה אפשר לעשות עם ה-API

מסמכים

רשימת מסמכים, פרטי מסמך והקובץ המקורי.

העלאה

שולחים מסמך חדש, והוא נסרק כמו כל מסמך אחר.

תיוג

מוסיפים ומסירים תגיות ממסמכים.

ספקים וייצוא

רשימת ספקים ויצירת קובצי ייצוא.

מתחילים בשלושה צעדים

  1. 1

    יוצרים מפתח API

    מנהל החשבון יוצר מפתח באפליקציית הווב, במחשב: Settings → API & integrations → Create key. המפתח מוצג פעם אחת בלבד.

  2. 2

    שולחים קריאה ראשונה

    מוסיפים את המפתח לכותרת Authorization כ-Bearer ומבקשים את רשימת המסמכים. מפתח רגיל הוא לקריאה בלבד; להעלאה ולתיוג צריך מפתח write.

  3. 3

    מקבלים JSON

    התשובה חוזרת עם המסמכים ועם nextCursor לעמוד הבא.

התיעוד המלא

כל מה שיש היום ב-rest.doxbox.io, באותו סדר: מדריך, 12 נקודות קצה, חיבור ל-Claude ומתכונים. התיעוד הטכני נשאר באנגלית.

Introduction

v1

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.

SettingValue
Base URLhttps://app.doxbox.io
Base path/api/v1
FormatJSON, UTF-8
AccessRead 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.

Quickstart

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"

Authentication

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.

Scopes

Every key carries one of two permission levels, chosen at creation. Calling a write endpoint with a read key returns 403 API_KEY_FORBIDDEN.

ScopeGrants
readRead documents, suppliers and tags, generate exports (default)
writeEverything in read, plus uploading documents and changing document tags

Conventions

The handful of rules that hold across every endpoint.

Pagination

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.

Rate limiting

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.

Quotas

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.

Duplicate handling

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.

Errors

A JSON body with a human message and, where useful, a machine-readable code.

{ "message": "API key has expired", "code": "API_KEY_EXPIRED" }
All error codes (11)
HTTPcodeMeaning
400-Invalid request (bad parameters or body)
400TAG_LIMIT_PER_DOCUMENTDocument already has 10 tags
401API_KEY_MISSINGNo Authorization: Bearer header
401API_KEY_INVALIDUnknown key
401API_KEY_REVOKEDKey was revoked
401API_KEY_EXPIREDKey is past its expiry
403API_KEY_FORBIDDENKey lacks the required scope (for example write)
403PLAN_LIMIT_EXCEEDEDMonthly document quota reached
404-Not found, or not in your account
404TAG_NOT_FOUNDTag not found, or not in your account
429RATE_LIMITEDRate limit exceeded (see Retry-After)

Field reference

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.

FieldValues
documentTypeInvoice · Receipt · InvoiceReceipt · CreditInvoice · TransactionAccount · Other
paymentStatusPaid · Unpaid
currencyILS · USD · EUR · GBP · JPY · AUD
tag colorteal · salmon · green · violet · sand · slate
tag sourcemanual (a person) · rule (a supplier rule) · suggested_accepted · auto
The document object (14 fields)

Fields marked (detail) appear only on GET /documents/{id}; the list returns a lighter subset.

FieldTypeNotes
idnumberStable document id.
documentNumberstring | nullInvoice or receipt number, as read from the document.
documentTypeenumSee the values above.
documentDateISO date | nullDate on the document.
poNumber (detail)string | nullPurchase-order number.
netAmount · vat · vatRate · totalAmountnumber | nullAmounts in currency; vatRate is a percentage.
currencyenumILS · USD · EUR · GBP · JPY · AUD.
paymentStatusenumPaid · Unpaid.
paymentDate (detail)ISO date | nullWhen it was marked paid.
description (detail)string | nullFree-text note.
uploadedAt (detail)ISO datetimeWhen it was added to DoxBox.
supplierName / supplier (detail)string / objectThe list returns the name; the detail endpoint returns { id, name, crn }.
tagsarray[{ id, name, color, source }], in the order they were added.
images (detail)arrayPage image ids [{ id }], fetched via /documents/{id}/file?image=.

Endpoints

11

Twelve endpoints under /api/v1. Every one except /health needs the key.

GET/api/v1/healthno auth

Service health and version. The one endpoint that needs no key, handy for uptime checks.

GET/api/v1/documents

List the account's documents, newest first. Cursor-paginated with limit and cursor.

QueryTypeNotes
limitinteger1 to 100, default 25
cursorintegerThe last document id from the previous page
tagsstringComma-separated tag ids, for example 7,12. Only documents carrying every listed tag (AND). Ids come from GET /tags.
GET/api/v1/documents/{id}

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.

GET/api/v1/documents/{id}/file

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).

POST/api/v1/documentsrequires write

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.

GET/api/v1/tags

The account tags (the labels a business puts on its documents), with how many documents carry each.

PUT/api/v1/documents/{id}/tagsrequires write

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.

BodyTypeNotes
tagIdsnumber[]The full list, at most 10 ids. [] removes every tag.
POST/api/v1/documents/{id}/tagsrequires write

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.

BodyTypeNotes
tagIdnumberAn id from GET /tags
DELETE/api/v1/documents/{id}/tags/{tagId}requires write

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.

GET/api/v1/suppliers

The account suppliers (those with documents), with per-supplier aggregates, sorted by total amount.

GET/api/v1/me/businesses

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).

POST/api/v1/exports

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.

FieldTypeNotes
exportTypestringexcel_monthly · csv · pdf_merged · zip
scopestringall_results (default) or selected
selectedDocumentIdsnumber[]Required when scope is selected
filters.yearnumberFor example 2026
filters.monthnumber1 to 12

DoxBox in Claude (MCP)

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 connectorLocal server
Forclaude.ai (web, desktop and mobile), Claude Code, and any MCP client that supports remote servers with OAuthClaude Code, Claude Desktop, Cursor and other local MCP clients
Addresshttps://app.doxbox.io/api/mcpdoxbox-mcp on npm (open source, MIT)
Sign-inYour DoxBox user: every business you choose to include, with a permission per businessOne API key = one account
InstallNothingNothing (npx), Node 18 or newer
Uploading filesNoYes

Remote connector

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.

Local server

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.

Tools (13)
ToolWhat it doesNeeds
doxbox_healthAPI status and which server the MCP points atnone
doxbox_list_businessesRemote connector only: the businesses in the connection, with the role, permission and defaultread
doxbox_list_documentsA page of documents, newest first (limit, cursor, tag_ids)read
doxbox_search_documentsDocuments by supplier, date range, payment status, type, amount or tagsread
doxbox_get_documentOne document: amounts, VAT, supplier with CRN, dates, tags, page idsread
doxbox_get_document_file_urlShort-lived signed URL for the original fileread
doxbox_list_suppliersSuppliers with document counts and totals, optional name filterread
doxbox_list_tagsThe account tags with document countsread
doxbox_create_exportExcel, CSV, merged PDF or ZIP of a month, as a download linkread
doxbox_set_document_tagsReplace the tags of a documentwrite
doxbox_add_document_tagAdd one tag to a documentwrite
doxbox_remove_document_tagRemove one tag from a documentwrite
doxbox_upload_documentsLocal server only: upload local PDF or image fileswrite

Recipes

RecipeWhat it shows
Page through all documentsFollow nextCursor until it returns null.
Automated monthly Excel exportCall POST /exports with excel_monthly for the month, then download fileUrl.

Try it in SwaggerBreaking changes ship under a new version, announced in advance.