Receipts – API reference

List imports

GET/api/v1/imports

Only imports whose target (contacts, invoices, receipts) the caller is allowed to read.

Any valid API key or OAuth token.

Query parameters

limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<ImportJob>required
- idstringrequired
- object"import_job"required
- provider"lexoffice" | "sevdesk" | "papierkram" | "generic"required
- entity"contacts" | "invoices" | "receipts"required
- status"uploaded" | "importing" | "completed" | "failed"required
- fileNamestringrequired
- delimiterstringrequired
- encodingstringrequired
- rowCountintegerrequired
  -9007199254740991–9007199254740991
- headersArray<string>required
- mappingobjectrequired
  Target field → column heading of the CSV file (null = do not import)
- fieldsArray<object>required
  - idstringrequired
  - labelstringrequired
  - typestringrequired
  - requiredbooleanrequired
- sampleArray<object>required
  The first lines of the file
- countsobject | nullrequired
  - totalintegerrequired
    -9007199254740991–9007199254740991
  - createdintegerrequired
    -9007199254740991–9007199254740991
  - duplicatesintegerrequired
    -9007199254740991–9007199254740991
  - skippedintegerrequired
    -9007199254740991–9007199254740991
  - errorsintegerrequired
    -9007199254740991–9007199254740991
- errorsArray<object>required
  - rowintegerrequired
    -9007199254740991–9007199254740991
  - messagestringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
- completedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/imports' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "import_job",
      "provider": "lexoffice",
      "entity": "contacts",
      "status": "uploaded",
      "fileName": "string",
      "delimiter": "string",
      "encoding": "string",
      "rowCount": 0,
      "headers": [
        "string"
      ],
      "mapping": {},
      "fields": [
        {
          "id": "string",
          "label": "string",
          "type": "string",
          "required": false
        }
      ],
      "sample": [
        {}
      ],
      "counts": {
        "total": 0,
        "created": 0,
        "duplicates": 0,
        "skipped": 0,
        "errors": 0
      },
      "errors": [
        {
          "row": 0,
          "message": "string"
        }
      ],
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z",
      "completedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

CSV export from Lexware Office (lexoffice), sevDesk, Papierkram or your own CSV in the field file, plus provider and entity (contacts, invoices, receipts). The response contains the detected columns, a suggested mapping (mapping) and the first rows. Then POST /imports/{id}/preview (validation, duplicates) and POST /imports/{id}/commit. Requires the write scope of the target: contacts:write, invoices:write or receipts:write respectively.

Any valid API key or OAuth token.

Body (multipart/form-data)

filestring (binary)required
text/csv, text/plain, application/vnd.ms-excel, application/csv, text/comma-separated-values, application/octet-stream, max. 5120 KB
provider"lexoffice" | "sevdesk" | "papierkram" | "generic"required
entity"contacts" | "invoices" | "receipts"required

Response 201 · ImportJob

idstringrequired
object"import_job"required
provider"lexoffice" | "sevdesk" | "papierkram" | "generic"required
entity"contacts" | "invoices" | "receipts"required
status"uploaded" | "importing" | "completed" | "failed"required
fileNamestringrequired
delimiterstringrequired
encodingstringrequired
rowCountintegerrequired
-9007199254740991–9007199254740991
headersArray<string>required
mappingobjectrequired
Target field → column heading of the CSV file (null = do not import)
fieldsArray<object>required
- idstringrequired
- labelstringrequired
- typestringrequired
- requiredbooleanrequired
sampleArray<object>required
The first lines of the file
countsobject | nullrequired
- totalintegerrequired
  -9007199254740991–9007199254740991
- createdintegerrequired
  -9007199254740991–9007199254740991
- duplicatesintegerrequired
  -9007199254740991–9007199254740991
- skippedintegerrequired
  -9007199254740991–9007199254740991
- errorsintegerrequired
  -9007199254740991–9007199254740991
errorsArray<object>required
- rowintegerrequired
  -9007199254740991–9007199254740991
- messagestringrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)
completedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 413, 415, 429, 500

curl

curl -X POST 'https://www.debt-flow.io/api/v1/imports' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file' \
  -F 'provider=…' \
  -F 'entity=…'

Response 201

{
  "id": "string",
  "object": "import_job",
  "provider": "lexoffice",
  "entity": "contacts",
  "status": "uploaded",
  "fileName": "string",
  "delimiter": "string",
  "encoding": "string",
  "rowCount": 0,
  "headers": [
    "string"
  ],
  "mapping": {},
  "fields": [
    {
      "id": "string",
      "label": "string",
      "type": "string",
      "required": false
    }
  ],
  "sample": [
    {}
  ],
  "counts": {
    "total": 0,
    "created": 0,
    "duplicates": 0,
    "skipped": 0,
    "errors": 0
  },
  "errors": [
    {
      "row": 0,
      "message": "string"
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z",
  "completedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve import

GET/api/v1/imports/{id}

Any valid API key or OAuth token.

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · ImportJob

idstringrequired
object"import_job"required
provider"lexoffice" | "sevdesk" | "papierkram" | "generic"required
entity"contacts" | "invoices" | "receipts"required
status"uploaded" | "importing" | "completed" | "failed"required
fileNamestringrequired
delimiterstringrequired
encodingstringrequired
rowCountintegerrequired
-9007199254740991–9007199254740991
headersArray<string>required
mappingobjectrequired
Target field → column heading of the CSV file (null = do not import)
fieldsArray<object>required
- idstringrequired
- labelstringrequired
- typestringrequired
- requiredbooleanrequired
sampleArray<object>required
The first lines of the file
countsobject | nullrequired
- totalintegerrequired
  -9007199254740991–9007199254740991
- createdintegerrequired
  -9007199254740991–9007199254740991
- duplicatesintegerrequired
  -9007199254740991–9007199254740991
- skippedintegerrequired
  -9007199254740991–9007199254740991
- errorsintegerrequired
  -9007199254740991–9007199254740991
errorsArray<object>required
- rowintegerrequired
  -9007199254740991–9007199254740991
- messagestringrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)
completedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/imports/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "import_job",
  "provider": "lexoffice",
  "entity": "contacts",
  "status": "uploaded",
  "fileName": "string",
  "delimiter": "string",
  "encoding": "string",
  "rowCount": 0,
  "headers": [
    "string"
  ],
  "mapping": {},
  "fields": [
    {
      "id": "string",
      "label": "string",
      "type": "string",
      "required": false
    }
  ],
  "sample": [
    {}
  ],
  "counts": {
    "total": 0,
    "created": 0,
    "duplicates": 0,
    "skipped": 0,
    "errors": 0
  },
  "errors": [
    {
      "row": 0,
      "message": "string"
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z",
  "completedAt": "2026-11-01T09:30:00.000Z"
}

Discard import

DELETE/api/v1/imports/{id}

Deletes the job and the uploaded file. Records that have already been imported are kept.

Any valid API key or OAuth token.

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/imports/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Run import

POST/api/v1/imports/{id}/commit

Creates the validated records: contacts (customers/suppliers), invoices (as finalised legacy documents with their original number, without a number range) or receipts (status review, without a file). Rows with errors are skipped, as are duplicates by default. A job can only be run once (409 import_completed).

Any valid API key or OAuth token.

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · ImportCommitRequest

mappingobjectrequired
Target field → column heading of the CSV file (null = do not import)
defaultRole"customer" | "supplier"
Default: "customer"
skipDuplicatesboolean
Skip duplicates (recommended)
Default: true

Response 200 · ImportJob

idstringrequired
object"import_job"required
provider"lexoffice" | "sevdesk" | "papierkram" | "generic"required
entity"contacts" | "invoices" | "receipts"required
status"uploaded" | "importing" | "completed" | "failed"required
fileNamestringrequired
delimiterstringrequired
encodingstringrequired
rowCountintegerrequired
-9007199254740991–9007199254740991
headersArray<string>required
mappingobjectrequired
Target field → column heading of the CSV file (null = do not import)
fieldsArray<object>required
- idstringrequired
- labelstringrequired
- typestringrequired
- requiredbooleanrequired
sampleArray<object>required
The first lines of the file
countsobject | nullrequired
- totalintegerrequired
  -9007199254740991–9007199254740991
- createdintegerrequired
  -9007199254740991–9007199254740991
- duplicatesintegerrequired
  -9007199254740991–9007199254740991
- skippedintegerrequired
  -9007199254740991–9007199254740991
- errorsintegerrequired
  -9007199254740991–9007199254740991
errorsArray<object>required
- rowintegerrequired
  -9007199254740991–9007199254740991
- messagestringrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)
completedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 410, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/imports/ID/commit' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mapping": {},
  "defaultRole": "customer",
  "skipDuplicates": true
}'

Response 200

{
  "id": "string",
  "object": "import_job",
  "provider": "lexoffice",
  "entity": "contacts",
  "status": "uploaded",
  "fileName": "string",
  "delimiter": "string",
  "encoding": "string",
  "rowCount": 0,
  "headers": [
    "string"
  ],
  "mapping": {},
  "fields": [
    {
      "id": "string",
      "label": "string",
      "type": "string",
      "required": false
    }
  ],
  "sample": [
    {}
  ],
  "counts": {
    "total": 0,
    "created": 0,
    "duplicates": 0,
    "skipped": 0,
    "errors": 0
  },
  "errors": [
    {
      "row": 0,
      "message": "string"
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z",
  "completedAt": "2026-11-01T09:30:00.000Z"
}

Import preview

POST/api/v1/imports/{id}/preview

Applies the column mapping and checks each row: new, duplicate (already exists or appears twice in the file) or error. Errors and duplicates are listed first. Saves the mapping on the job; otherwise changes nothing.

Any valid API key or OAuth token.

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · ImportPreviewRequest

mappingobjectrequired
Target field → column heading of the CSV file (null = do not import)
defaultRole"customer" | "supplier"
Contacts only: contact type if no column is mapped
Default: "customer"
limitinteger
1–500 · Default: 200

Response 200 · ImportPreview

object"import_preview"required
countsobjectrequired
- totalintegerrequired
  -9007199254740991–9007199254740991
- newintegerrequired
  -9007199254740991–9007199254740991
- duplicatesintegerrequired
  -9007199254740991–9007199254740991
- errorsintegerrequired
  -9007199254740991–9007199254740991
rowsArray<object>required
- rowintegerrequired
  Line number in the file (1 = first data row)
  -9007199254740991–9007199254740991
- status"new" | "duplicate" | "error"required
- recordobjectrequired
- duplicateOfobject | nullrequired
  - typestringrequired
  - idstring | nullrequired
  - labelstringrequired
- messagesArray<string>required

Possible errors: 400, 401, 403, 404, 410, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/imports/ID/preview' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mapping": {},
  "defaultRole": "customer",
  "limit": 200
}'

Response 200

{
  "object": "import_preview",
  "counts": {
    "total": 0,
    "new": 0,
    "duplicates": 0,
    "errors": 0
  },
  "rows": [
    {
      "row": 0,
      "status": "new",
      "record": {},
      "duplicateOf": {
        "type": "string",
        "id": "string",
        "label": "string"
      },
      "messages": [
        "string"
      ]
    }
  ]
}

Expense categories with accounts (SKR03/SKR04)

GET/api/v1/receipt-categories

Categories for a receipt's category, with suggested accounts according to the DATEV standard charts of accounts SKR03 and SKR04.

Permission: receipts:read

Response 200 · ReceiptCategoryList

object"list"required
dataArray<object>required
- idenumrequired
  Expense category (see GET /receipt-categories)
  Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
- labelstringrequired
- hintstringrequired
- skr03stringrequired
- skr04stringrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipt-categories' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "goods",
      "label": "string",
      "hint": "string",
      "skr03": "string",
      "skr04": "string"
    }
  ]
}

Retrieve inbound email address for receipts

GET/api/v1/receipt-inbox

Personal address belege-<kennung>@in.debt-flow.io. Attachments (PDF, images, e-invoices) sent to this address are created as receipts.

Permission: receipts:read

Response 200 · ReceiptInbox

object"receipt_inbox"required
addressstring | nullrequired
belege-<identifier>@… – null until set up
activebooleanrequired
allowedSendersArray<string>required
Only accept these senders (email or @domain); empty = all
receivedCountintegerrequired
-9007199254740991–9007199254740991
lastReceivedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipt-inbox' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "receipt_inbox",
  "address": "string",
  "active": false,
  "allowedSenders": [
    "string"
  ],
  "receivedCount": 0,
  "lastReceivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Set up or update inbound email address

PATCH/api/v1/receipt-inbox

active: true sets up the address the first time. allowedSenders restricts receiving to specific senders (email or @domain.de).

Permission: receipts:write

Body (JSON) · ReceiptInboxUpdate

activeboolean
allowedSendersArray<string>

Response 200 · ReceiptInbox

object"receipt_inbox"required
addressstring | nullrequired
belege-<identifier>@… – null until set up
activebooleanrequired
allowedSendersArray<string>required
Only accept these senders (email or @domain); empty = all
receivedCountintegerrequired
-9007199254740991–9007199254740991
lastReceivedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/receipt-inbox' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "active": false,
  "allowedSenders": [
    "string"
  ]
}'

Response 200

{
  "object": "receipt_inbox",
  "address": "string",
  "active": false,
  "allowedSenders": [
    "string"
  ],
  "receivedCount": 0,
  "lastReceivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Generate new inbound email address

POST/api/v1/receipt-inbox/rotate

Assigns a new identifier. The previous address immediately stops accepting receipts (e.g. in case of spam).

Permission: receipts:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Response 200 · ReceiptInbox

object"receipt_inbox"required
addressstring | nullrequired
belege-<identifier>@… – null until set up
activebooleanrequired
allowedSendersArray<string>required
Only accept these senders (email or @domain); empty = all
receivedCountintegerrequired
-9007199254740991–9007199254740991
lastReceivedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/receipt-inbox/rotate' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "receipt_inbox",
  "address": "string",
  "active": false,
  "allowedSenders": [
    "string"
  ],
  "receivedCount": 0,
  "lastReceivedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

List receipts

GET/api/v1/receipts

Newest first. Filter by status (inbox, processing, review, booked), source and payment status.

Permission: receipts:read

Query parameters

status"inbox" | "processing" | "review" | "booked"
source"upload" | "app" | "email" | "import"
paymentStatus"open" | "paid"
limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<Receipt>required
- idstringrequired
- object"receipt"required
- status"inbox" | "processing" | "review" | "booked"required
- source"upload" | "app" | "email" | "import"required
- numberstring | nullrequired
  Internal document number (number range “receipt”), assigned on posting
- fileReceiptFile | nullrequired
  Original file; null for imported receipts without a file
  - fileNamestringrequired
  - contentTypestringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - sha256stringrequired
    SHA-256 of the original (GoBD evidence, duplicate check)
- supplierContactIdstring | nullrequired
- supplierNamestring | nullrequired
- supplierVatIdstring | nullrequired
- supplierIbanstring | nullrequired
- documentNumberstring | nullrequired
  Supplier's invoice number
- documentDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- dueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- currency"EUR"required
- totalsReceiptTotalsrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- taxLinesArray<ReceiptTaxLine>required
  - taxRatenumberrequired
    Tax rate in per cent (19, 7, 0 …)
    0–100
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- categoryenum | nullrequired
  Expense category (see GET /receipt-categories)
  Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
- postingFactsReceiptPostingFacts | nullrequired
  Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
  - softwareKind"subscription" | "purchase" | "own_development" | null
    Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
  - durableAssetboolean | null
    Independently usable asset with a useful life of more than one year
  - businessEntertainmentboolean | null
    Business entertainment (70/30 split)
  - giftValuePerRecipientCentsinteger | null
    Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
    0–9007199254740991
  - giftRecipientsstring | null
    Gifts: recipient (record-keeping obligation § 4 (7) EStG)
    max. 500 characters
  - travelKind"fares" | "lodging" | "meals" | "other" | null
    Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
- accountsobject | nullrequired
  Suggested account for the category (SKR03/SKR04)
  - skr03stringrequired
  - skr04stringrequired
- descriptionstring | nullrequired
- notesstring | nullrequired
- paymentStatus"open" | "paid"required
- paidAtstring (date) | nullrequired
  Date (YYYY-MM-DD)
- bankTransactionIdstring | nullrequired
- einvoiceReceiptEInvoice | nullrequired
  Detected e-invoice (structured data instead of OCR)
  - format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
  - profilestring | nullrequired
    Specification identifier (BT-24)
  - formatLabelstring | nullrequired
  - typeCodestring | nullrequired
    BT-3 invoice type code (380, 381 …)
  - numberstring | nullrequired
  - currencystring | nullrequired
  - lineCountintegerrequired
    -9007199254740991–9007199254740991
  - linesArray<object>required
    Lines (at most 200; all via /e-invoice)
  - vatBreakdownArray<object>required
  - payableCentsinteger | nullrequired
    -9007199254740991–9007199254740991
  - validationobject | nullrequired
  - parserWarningsArray<string>required
  - extensionobject | nullrequired
    XRechnung extension: fully preserved, display to follow (ER-10)
  - xmlobject | nullrequired
    Original XML (archived, § 147 AO)
- ocrReceiptOcrrequired
  - status"pending" | "running" | "done" | "failed" | "skipped"required
  - enginestring | nullrequired
    gemini-… (OCR) or einvoice (structured e-invoice)
  - confidencenumber | nullrequired
    0–1
  - errorstring | nullrequired
  - attemptsintegerrequired
    -9007199254740991–9007199254740991
  - processedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
- duplicateOfstring | nullrequired
  ID of a possibly identical receipt
- emailobject | nullrequired
  Origin when received by email
  - fromstringrequired
  - subjectstringrequired
  - receivedAtstring (date-time)required
    Timestamp (ISO 8601)
- importobject | nullrequired
  - providerstringrequired
  - jobIdstringrequired
  - rowintegerrequired
    -9007199254740991–9007199254740991
- lockedbooleanrequired
- bookedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "receipt",
      "status": "inbox",
      "source": "upload",
      "number": "string",
      "file": {
        "fileName": null,
        "contentType": null,
        "size": null,
        "sha256": null
      },
      "supplierContactId": "string",
      "supplierName": "string",
      "supplierVatId": "string",
      "supplierIban": "string",
      "documentNumber": "string",
      "documentDate": "2026-11-01",
      "dueDate": "2026-11-01",
      "currency": "EUR",
      "totals": {
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      },
      "taxLines": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "taxTreatment": "regular",
      "category": "goods",
      "postingFacts": {
        "softwareKind": null,
        "durableAsset": null,
        "businessEntertainment": null,
        "giftValuePerRecipientCents": null,
        "giftRecipients": null,
        "travelKind": null
      },
      "accounts": {
        "skr03": "string",
        "skr04": "string"
      },
      "description": "string",
      "notes": "string",
      "paymentStatus": "open",
      "paidAt": "2026-11-01",
      "bankTransactionId": "string",
      "einvoice": {
        "format": null,
        "profile": null,
        "formatLabel": null,
        "typeCode": null,
        "number": null,
        "currency": null,
        "lineCount": null,
        "lines": null,
        "vatBreakdown": null,
        "payableCents": null,
        "validation": null,
        "parserWarnings": null,
        "extension": null,
        "xml": null
      },
      "ocr": {
        "status": "pending",
        "engine": "string",
        "confidence": null,
        "error": "string",
        "attempts": 0,
        "processedAt": null
      },
      "duplicateOf": "string",
      "email": {
        "from": "string",
        "subject": "string",
        "receivedAt": "2026-11-01T09:30:00.000Z"
      },
      "import": {
        "provider": "string",
        "jobId": "string",
        "row": 0
      },
      "locked": false,
      "bookedAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Upload receipt

POST/api/v1/receipts

File (PDF, image or e-invoice as XML/ZUGFeRD PDF) as multipart/form-data in the file field. E-invoices are read as structured data, all others via OCR (supplier, date, amounts per tax rate, category). With process=sync (default), the response already contains the recognised values; with async, query the status via GET /receipts/{id}.

Permission: receipts:write

Body (multipart/form-data)

filestring (binary)required
application/pdf, image/jpeg, image/png, image/webp, image/heic, image/heif, application/xml, text/xml, max. 9216 KB
notesstring
max. 2000 characters
process"sync" | "async" | "none"
OCR: sync (wait), async (background) or none
Default: "sync"

Response 201 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 413, 415, 429, 500

curl

curl -X POST 'https://www.debt-flow.io/api/v1/receipts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file' \
  -F 'notes=…' \
  -F 'process=…'

Response 201

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve receipt

GET/api/v1/receipts/{id}

Permission: receipts:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update receipt

PATCH/api/v1/receipts/{id}

Only the fields you pass are changed. Amounts via taxLines (per tax rate) or grossCents + taxRate; the server calculates the totals. Posted receipts are finalised – then only paymentStatus and paidAt can be changed (otherwise 409 document_locked).

Permission: receipts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · ReceiptUpdate

supplierContactIdstring | null
max. 128 characters
supplierNamestring | null
max. 200 characters
supplierVatIdstring | null | ""
supplierIbanstring | null
documentNumberstring | null
max. 80 characters
documentDatestring (date) | null
Date (YYYY-MM-DD)
dueDatestring (date) | null
Date (YYYY-MM-DD)
taxLinesArray<ReceiptTaxLine>
Net/tax per tax rate; totals are calculated from these
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
grossCentsinteger
Only without taxLines: gross amount; with taxRate, net/tax is calculated
-100000000000–100000000000
taxRatenumber
Tax rate in per cent (19, 7, 0 …)
0–100
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"
Tax treatment of the receipt
categoryenum | null
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | null
Facts for the account assignment engine (tax assistant)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
descriptionstring | null
max. 500 characters
notesstring | null
max. 2000 characters
paymentStatus"open" | "paid"
paidAtstring (date) | null
Date (YYYY-MM-DD)

Response 200 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/receipts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "grossCents": 0,
  "taxRate": 0,
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01"
}'

Response 200

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete receipt

DELETE/api/v1/receipts/{id}

Only unposted receipts. Posted receipts are subject to the statutory retention obligation (409 document_locked).

Permission: receipts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/receipts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Post receipt (finalise)

POST/api/v1/receipts/{id}/book

Assigns the internal document number (receipt number range, without gaps) and finalises the receipt (GoBD). After that, only the payment status and bank match can be changed. Prerequisites: document date, supplier, amount and category. If a duplicate is suspected, 409 possible_duplicate – post anyway with confirmDuplicate: true.

Permission: receipts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON)

confirmDuplicateboolean
Post despite duplicate warning

Response 200 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/receipts/ID/book' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "confirmDuplicate": false
}'

Response 200

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Read the full e-invoice of a receipt

GET/api/v1/receipts/{id}/e-invoice

Reads the archived receipt file again with the full e-invoice parser: all lines, taxes, sub-lines and third-party payments of the XRechnung extension (invoice.extension), the validation report (structure and – if configured – the official KoSIT validator in external) and the original XML (originalXml). 404 if the receipt is not an e-invoice.

Permission: receipts:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200

container"xml" | "pdf"required
plain XML file or PDF with embedded XML (ZUGFeRD/Factur-X)
syntax"ubl" | "cii"required
profile"en16931" | "xrechnung"required
rule set detected from BT-24
formatLabelstringrequired
e.g. “XRechnung 3.0 (UBL)”
embeddedFilenamestring | nullrequired
Name of the embedded XML for PDF
invoiceEInvoicerequired
- customizationIdstringrequired
  BT-24 Specification identifier
  max. 300 characters
- profileIdstring
  BT-23 Business process
  max. 300 characters
- numberstringrequired
  BT-1 Invoice number
  max. 200 characters
- issueDatestringrequired
  BT-2 Invoice date (YYYY-MM-DD)
  max. 10 characters
- typeCodestringrequired
  BT-3 Invoice type (380 invoice, 381 credit note, 384 corrected invoice …)
  max. 10 characters
- currencystringrequired
  BT-5 Currency
  max. 3 characters
- taxPointDatestring
  BT-7
  max. 10 characters
- dueDatestring
  BT-9 Due date
  max. 10 characters
- buyerReferencestring
  BT-10 Buyer reference / Leitweg-ID
  max. 200 characters
- projectReferencestring
  BT-11
  max. 200 characters
- contractReferencestring
  BT-12
  max. 200 characters
- orderReferencestring
  BT-13 Purchase order number
  max. 200 characters
- salesOrderReferencestring
  BT-14 Sales order number
  max. 200 characters
- accountingReferencestring
  BT-19 Accounting reference
  max. 200 characters
- notesArray<object>required
  BG-1 Notes
  - subjectCodestring
    max. 10 characters
  - textstringrequired
    max. 10000 characters
- precedingInvoicesArray<object>required
  BG-3 Reference to preceding invoices
  - numberstringrequired
    max. 200 characters
  - issueDatestring
    max. 10 characters
- sellerEInvoicePartyrequired
  BG-4 Seller
  - namestringrequired
    BT-27/44 Name
    max. 300 characters
  - tradingNamestring
    BT-28/45 Trading name
    max. 300 characters
  - identifiersArray<object>required
    BT-29/46 Identifiers
  - legalRegistrationIdobject
    BT-30/47 Registration number
  - vatIdstring
    BT-31/48 VAT ID
    max. 30 characters
  - taxNumberstring
    BT-32 Tax number (seller only)
    max. 30 characters
  - additionalLegalInfostring
    BT-33 Additional legal information (seller only)
    max. 1000 characters
  - electronicAddressobject
    BT-34/49 Electronic address (scheme EM = email, 0204 = Leitweg-ID)
  - addressEInvoiceAddressrequired
  - contactobject
    BG-6/BG-9 Contact
- buyerEInvoicePartyrequired
  BG-7 Buyer
  - namestringrequired
    BT-27/44 Name
    max. 300 characters
  - tradingNamestring
    BT-28/45 Trading name
    max. 300 characters
  - identifiersArray<object>required
    BT-29/46 Identifiers
  - legalRegistrationIdobject
    BT-30/47 Registration number
  - vatIdstring
    BT-31/48 VAT ID
    max. 30 characters
  - taxNumberstring
    BT-32 Tax number (seller only)
    max. 30 characters
  - additionalLegalInfostring
    BT-33 Additional legal information (seller only)
    max. 1000 characters
  - electronicAddressobject
    BT-34/49 Electronic address (scheme EM = email, 0204 = Leitweg-ID)
  - addressEInvoiceAddressrequired
  - contactobject
    BG-6/BG-9 Contact
- payeeNamestring
  BT-59 Payee, if different
  max. 300 characters
- deliveryobject
  - partyNamestring
    BT-70
    max. 300 characters
  - datestring
    BT-72 Delivery/service date
    max. 10 characters
  - addressEInvoiceAddress
    BG-15 Delivery address
- invoicingPeriodobject
  BG-14 Invoicing period
  - startstring
    max. 10 characters
  - endstring
    max. 10 characters
- paymentMeansEInvoicePaymentMeans
  BG-16
  - typeCodestringrequired
    BT-81 Payment means (UNTDID 4461, 58 = SEPA credit transfer)
    max. 10 characters
  - textstring
    BT-82
    max. 300 characters
  - remittanceInfostring
    BT-83 Payment reference
    max. 300 characters
  - accountsArray<object>required
    BG-17 Credit transfer
  - cardobject
    BG-18 Card payment (last digits only)
  - directDebitobject
    BG-19 Direct debit
- paymentTermsstring
  BT-20 Payment terms
  max. 2000 characters
- allowanceChargesArray<EInvoiceAllowanceCharge>required
  BG-20/BG-21 Document-level allowances/charges
  - chargeIndicatorbooleanrequired
    true = surcharge, false = discount
  - amountCentsintegerrequired
    BT-92/99/136/141 Amount
    -9007199254740991–9007199254740991
  - baseAmountCentsinteger
    BT-93/100/137/142 Base amount
    -9007199254740991–9007199254740991
  - percentnumber
    BT-94/101/138/143 Percentage
  - reasonstring
    BT-97/104/139/144 Reason
    max. 500 characters
  - reasonCodestring
    BT-98/105/140/145 Reason (code)
    max. 10 characters
  - taxCategorystring
    BT-95/102 VAT category (document level only)
    max. 3 characters
  - taxRatenumber | null
    BT-96/103 VAT rate (document level only)
- totalsEInvoiceTotalsrequired
  BG-22
  - lineNetCentsintegerrequired
    BT-106 Sum of line net amounts
    -9007199254740991–9007199254740991
  - allowancesCentsintegerrequired
    BT-107 Sum of allowances
    -9007199254740991–9007199254740991
  - chargesCentsintegerrequired
    BT-108 Sum of charges
    -9007199254740991–9007199254740991
  - taxExclusiveCentsintegerrequired
    BT-109 Total net amount
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    BT-110 Total VAT
    -9007199254740991–9007199254740991
  - taxInclusiveCentsintegerrequired
    BT-112 Total gross amount
    -9007199254740991–9007199254740991
  - prepaidCentsintegerrequired
    BT-113 Already paid
    -9007199254740991–9007199254740991
  - roundingCentsintegerrequired
    BT-114 Rounding
    -9007199254740991–9007199254740991
  - payableCentsintegerrequired
    BT-115 Amount due
    -9007199254740991–9007199254740991
- vatBreakdownArray<EInvoiceVatBreakdown>required
  BG-23
  - categorystringrequired
    BT-118 Category
    max. 3 characters
  - ratenumber | nullrequired
    BT-119 Rate in percent (null for O)
  - taxableCentsintegerrequired
    BT-116 Taxable amount
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    BT-117 Tax amount
    -9007199254740991–9007199254740991
  - exemptionReasonstring
    BT-120 Exemption reason
    max. 1000 characters
  - exemptionReasonCodestring
    BT-121 Exemption reason (VATEX code)
    max. 30 characters
- linesArray<EInvoiceLine>required
  BG-25
  - idstringrequired
    BT-126 Line number
    max. 100 characters
  - parentLineIdstring
    parent line (CII ParentLineID, incoming only)
    max. 100 characters
  - statusReasonCodestring
    CII LineStatusReasonCode (DETAIL, GROUP, INFORMATION; incoming only)
    max. 20 characters
  - notestring
    BT-127 Line note
    max. 2000 characters
  - quantitynumberrequired
    BT-129 Quantity
  - unitCodestringrequired
    BT-130 Unit (UN/ECE Rec. 20/21)
    max. 10 characters
  - netAmountCentsintegerrequired
    BT-131 Line net amount
    -9007199254740991–9007199254740991
  - orderLineReferencestring
    BT-132 Purchase order line number
    max. 100 characters
  - periodobject
    BG-26 Invoice line period
  - allowanceChargesArray<EInvoiceAllowanceCharge>required
    BG-27/BG-28
  - netPriceCentsnumberrequired
    BT-146 Net price
  - grossPriceCentsnumber
    BT-148 Gross price (before price discount)
  - priceDiscountCentsnumber
    BT-147 Price discount
  - baseQuantitynumber
    BT-149 Base quantity
  - vatobjectrequired
  - itemobjectrequired
- attachmentsArray<EInvoiceAttachment>required
  BG-24
  - idstringrequired
    BT-122 Identifier
    max. 200 characters
  - descriptionstring
    BT-123
    max. 1000 characters
  - uristring
    BT-124 External location
    max. 1000 characters
  - filenamestring
    BT-125 File name
    max. 300 characters
  - mimeCodestring
    max. 100 characters
  - sizeBytesinteger
    -9007199254740991–9007199254740991
  - contentBase64string
    BT-125 Content (Base64)
- extensionEInvoiceExtensionData
  XRechnung extension: sub-lines, third-party payments (incoming only)
  - subLinesArray<EInvoiceSubLine>required
  - thirdPartyPaymentsArray<EInvoiceThirdPartyPayment>required
- language"de" | "en"
  Language of the free texts and the human-readable rendering (internal; EN 16931/XRechnung have no language field in the invoice header)
validationEInvoiceValidationReportrequired
- profile"en16931" | "xrechnung"required
- validbooleanrequired
  no errors (warnings allowed)
- errorCountintegerrequired
  -9007199254740991–9007199254740991
- warningCountintegerrequired
  -9007199254740991–9007199254740991
- issuesArray<EInvoiceValidationIssue>required
  - severity"error" | "warning"required
  - rulestringrequired
    Rule ID, e.g. BR-16, BR-DE-15, BR-S-02
  - fieldsArray<string>required
    affected business terms, e.g. ["BT-10"]
  - pathstring
    Path in the data model, e.g. seller.contact.phone
  - messagestringrequired
    human-readable message (German)
  - hintstring
    How to fix it (for your own invoices)
- scope"structure"required
  Structural check (mandatory fields, totals, tax rules). The full KoSIT check is returned in `external`.
receiptDraftEInvoiceReceiptDraftrequired
- documentType"invoice" | "credit_note"required
- supplierNamestringrequired
- supplierVatIdstring | nullrequired
- supplierTaxNumberstring | nullrequired
- supplierIbanstring | nullrequired
- supplierEmailstring | nullrequired
- documentNumberstringrequired
- documentDatestring | nullrequired
- dueDatestring | nullrequired
- currencystringrequired
- totalsobjectrequired
  - netCentsintegerrequired
    Amount in cents
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    Amount in cents
    -9007199254740991–9007199254740991
  - grossCentsintegerrequired
    Amount in cents
    -9007199254740991–9007199254740991
- payableCentsintegerrequired
  Amount in cents
  -9007199254740991–9007199254740991
- taxLinesArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    Amount in cents
    -9007199254740991–9007199254740991
- paymentReferencestring | nullrequired
- descriptionstringrequired
  Short description from the first line items
parserWarningsArray<string>required
unparseable or unknown details
xmlstring | nullrequired
extracted XML (PDF only)
externalEInvoiceExternalValidationReport | null
Result of the official KoSIT validator (only if requested and the service is configured)
- status"passed" | "failed" | "unavailable" | "skipped"required
- mode"required" | "optional" | "off"required
- documentKind"xml" | "zugferd_pdf"required
- sha256stringrequired
  SHA-256 of the validated document
- checkedAtstringrequired
  Time of validation (ISO 8601)
- baselinestringrequired
  Validation basis (versions, ER-09)
- resultsArray<EInvoiceExternalValidatorResult>required
  - validator"kosit" | "verapdf" | "mustang"required
  - versionstring | nullrequired
    version reported by the service or configured
  - status"passed" | "failed" | "unavailable" | "skipped"required
  - scenariostring | nullrequired
    KoSIT scenario, veraPDF profile or ZUGFeRD profile
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - messagesArray<EInvoiceExternalValidationMessage>required
    at most 200 messages
  - durationMsinteger | nullrequired
    -9007199254740991–9007199254740991
  - errorstring | nullrequired
    technical error (only for unavailable)
originalXmlstringrequired
XML of the e-invoice (for a PDF: the embedded file)

Possible errors: 400, 401, 403, 404, 422, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipts/ID/e-invoice' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "container": "xml",
  "syntax": "ubl",
  "profile": "en16931",
  "formatLabel": "string",
  "embeddedFilename": "string",
  "invoice": {
    "customizationId": "string",
    "profileId": "string",
    "number": "string",
    "issueDate": "string",
    "typeCode": "string",
    "currency": "string",
    "taxPointDate": "string",
    "dueDate": "string",
    "buyerReference": "string",
    "projectReference": "string",
    "contractReference": "string",
    "orderReference": "string",
    "salesOrderReference": "string",
    "accountingReference": "string",
    "notes": [],
    "precedingInvoices": [],
    "seller": {
      "name": "string",
      "tradingName": "string",
      "identifiers": [],
      "legalRegistrationId": {
        "id": "string",
        "scheme": "string"
      },
      "vatId": "string",
      "taxNumber": "string",
      "additionalLegalInfo": "string",
      "electronicAddress": {
        "scheme": "string",
        "value": "string"
      },
      "address": {
        "line1": null,
        "line2": null,
        "line3": null,
        "city": null,
        "postCode": null,
        "subdivision": null,
        "countryCode": null
      },
      "contact": {
        "name": "string",
        "phone": "string",
        "email": "string"
      }
    },
    "buyer": {
      "name": "string",
      "tradingName": "string",
      "identifiers": [],
      "legalRegistrationId": {
        "id": "string",
        "scheme": "string"
      },
      "vatId": "string",
      "taxNumber": "string",
      "additionalLegalInfo": "string",
      "electronicAddress": {
        "scheme": "string",
        "value": "string"
      },
      "address": {
        "line1": null,
        "line2": null,
        "line3": null,
        "city": null,
        "postCode": null,
        "subdivision": null,
        "countryCode": null
      },
      "contact": {
        "name": "string",
        "phone": "string",
        "email": "string"
      }
    },
    "payeeName": "string",
    "delivery": {
      "partyName": "string",
      "date": "string",
      "address": {
        "line1": "string",
        "line2": "string",
        "line3": "string",
        "city": "string",
        "postCode": "string",
        "subdivision": "string",
        "countryCode": "string"
      }
    },
    "invoicingPeriod": {
      "start": "string",
      "end": "string"
    },
    "paymentMeans": {
      "typeCode": "string",
      "text": "string",
      "remittanceInfo": "string",
      "accounts": [],
      "card": {
        "pan": "string",
        "holder": "string"
      },
      "directDebit": {
        "mandateId": "string",
        "creditorId": "string",
        "debitedAccount": "string"
      }
    },
    "paymentTerms": "string",
    "allowanceCharges": [],
    "totals": {
      "lineNetCents": 0,
      "allowancesCents": 0,
      "chargesCents": 0,
      "taxExclusiveCents": 0,
      "taxCents": 0,
      "taxInclusiveCents": 0,
      "prepaidCents": 0,
      "roundingCents": 0,
      "payableCents": 0
    },
    "vatBreakdown": [
      {
        "category": "string",
        "rate": 0,
        "taxableCents": 0,
        "taxCents": 0,
        "exemptionReason": "string",
        "exemptionReasonCode": "string"
      }
    ],
    "lines": [
      {
        "id": "string",
        "parentLineId": "string",
        "statusReasonCode": "string",
        "note": "string",
        "quantity": 0,
        "unitCode": "string",
        "netAmountCents": 0,
        "orderLineReference": "string",
        "period": {
          "start": null,
          "end": null
        },
        "allowanceCharges": [],
        "netPriceCents": 0,
        "grossPriceCents": 0,
        "priceDiscountCents": 0,
        "baseQuantity": 0,
        "vat": {
          "category": null,
          "rate": null
        },
        "item": {
          "name": null,
          "description": null,
          "sellerId": null,
          "buyerId": null,
          "standardId": null,
          "classifications": null,
          "originCountry": null,
          "attributes": null
        }
      }
    ],
    "attachments": [],
    "extension": {
      "subLines": [],
      "thirdPartyPayments": []
    },
    "language": "de"
  },
  "validation": {
    "profile": "en16931",
    "valid": false,
    "errorCount": 0,
    "warningCount": 0,
    "issues": [
      {
        "severity": "error",
        "rule": "string",
        "fields": [
          null
        ],
        "path": "string",
        "message": "string",
        "hint": "string"
      }
    ],
    "scope": "structure"
  },
  "receiptDraft": {
    "documentType": "invoice",
    "supplierName": "string",
    "supplierVatId": "string",
    "supplierTaxNumber": "string",
    "supplierIban": "string",
    "supplierEmail": "string",
    "documentNumber": "string",
    "documentDate": "string",
    "dueDate": "string",
    "currency": "string",
    "totals": {
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0
    },
    "payableCents": 0,
    "taxLines": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0
      }
    ],
    "paymentReference": "string",
    "description": "string"
  },
  "parserWarnings": [
    "string"
  ],
  "xml": "string",
  "external": {
    "status": "passed",
    "mode": "required",
    "documentKind": "xml",
    "sha256": "string",
    "checkedAt": "string",
    "baseline": "string",
    "results": [
      {
        "validator": null,
        "version": null,
        "status": null,
        "scenario": null,
        "errorCount": null,
        "warningCount": null,
        "messages": null,
        "durationMs": null,
        "error": null
      }
    ]
  },
  "originalXml": "string"
}

Download receipt file

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

Original file, unchanged (for the SHA-256, see file.sha256). XML is delivered as a download.

Permission: receipts:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200

File (application/octet-stream).

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/receipts/ID/file' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Replace or add receipt file

PUT/api/v1/receipts/{id}/file

Only unposted receipts, e.g. for imported receipts without a file. Recognition is then scheduled again.

Permission: receipts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (multipart/form-data)

filestring (binary)required
application/pdf, image/jpeg, image/png, image/webp, image/heic, image/heif, application/xml, text/xml, max. 9216 KB

Response 200 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 413, 415, 429, 500

curl

curl -X PUT 'https://www.debt-flow.io/api/v1/receipts/ID/file' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file'

Response 200

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Re-run receipt recognition

POST/api/v1/receipts/{id}/process

Restarts recognition (e-invoice or OCR). With overwrite: true, fields that are already filled in are also overwritten. If the AI quota is exhausted, ocr.status remains pending and recognition is retried automatically.

Permission: receipts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON)

overwriteboolean
Default: false

Response 200 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/receipts/ID/process' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "overwrite": false
}'

Response 200

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Upload receipt photo from the app

POST/api/v1/receipts/photos

For mobile apps: photo (JPEG, PNG, WebP, HEIC) in the file field. Responds immediately with 202 and status inbox; OCR runs in the background (event receipt.processed or GET /receipts/{id}). Recommendation: resize the photo to a maximum of 2500 px on the long edge, JPEG quality 80 %.

Permission: receipts:write

Body (multipart/form-data)

filestring (binary)required
image/jpeg, image/png, image/webp, image/heic, image/heif, max. 9216 KB
notesstring
max. 2000 characters
capturedAtstring (date-time)
Capture time in the app

Response 202 · Receipt

idstringrequired
object"receipt"required
status"inbox" | "processing" | "review" | "booked"required
source"upload" | "app" | "email" | "import"required
numberstring | nullrequired
Internal document number (number range “receipt”), assigned on posting
fileReceiptFile | nullrequired
Original file; null for imported receipts without a file
- fileNamestringrequired
- contentTypestringrequired
- sizeintegerrequired
  -9007199254740991–9007199254740991
- sha256stringrequired
  SHA-256 of the original (GoBD evidence, duplicate check)
supplierContactIdstring | nullrequired
supplierNamestring | nullrequired
supplierVatIdstring | nullrequired
supplierIbanstring | nullrequired
documentNumberstring | nullrequired
Supplier's invoice number
documentDatestring (date) | nullrequired
Date (YYYY-MM-DD)
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
currency"EUR"required
totalsReceiptTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxLinesArray<ReceiptTaxLine>required
- taxRatenumberrequired
  Tax rate in per cent (19, 7, 0 …)
  0–100
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
categoryenum | nullrequired
Expense category (see GET /receipt-categories)
Values: goods, goods_reduced, subcontractors, rent, utilities, cleaning, insurance, fees, vehicle_tax, vehicle_insurance, vehicle_running, vehicle_repairs, vehicle_leasing, advertising, gifts, entertainment, travel, travel_fares, travel_lodging, travel_meals, packaging, repairs, software, postage, phone, internet, office_supplies, literature, training, legal_advice, bookkeeping, equipment_rent, bank_fees, tools, low_value_assets, fixed_assets, other
postingFactsReceiptPostingFacts | nullrequired
Facts for the account assignment (low-value assets, software, entertainment, gifts, travel expenses)
- softwareKind"subscription" | "purchase" | "own_development" | null
  Software: subscription = subscription/maintenance, purchase = purchase, own_development = in-house development
- durableAssetboolean | null
  Independently usable asset with a useful life of more than one year
- businessEntertainmentboolean | null
  Business entertainment (70/30 split)
- giftValuePerRecipientCentsinteger | null
  Gifts: value of all gifts to the same recipient in the financial year (net, gross for small businesses) in cents
  0–9007199254740991
- giftRecipientsstring | null
  Gifts: recipient (record-keeping obligation § 4 (7) EStG)
  max. 500 characters
- travelKind"fares" | "lodging" | "meals" | "other" | null
  Travel expenses: fares = fares, lodging = accommodation, meals = meals, other = incidental costs
accountsobject | nullrequired
Suggested account for the category (SKR03/SKR04)
- skr03stringrequired
- skr04stringrequired
descriptionstring | nullrequired
notesstring | nullrequired
paymentStatus"open" | "paid"required
paidAtstring (date) | nullrequired
Date (YYYY-MM-DD)
bankTransactionIdstring | nullrequired
einvoiceReceiptEInvoice | nullrequired
Detected e-invoice (structured data instead of OCR)
- format"zugferd" | "xrechnung_cii" | "xrechnung_ubl"required
- profilestring | nullrequired
  Specification identifier (BT-24)
- formatLabelstring | nullrequired
- typeCodestring | nullrequired
  BT-3 invoice type code (380, 381 …)
- numberstring | nullrequired
- currencystring | nullrequired
- lineCountintegerrequired
  -9007199254740991–9007199254740991
- linesArray<object>required
  Lines (at most 200; all via /e-invoice)
  - idstringrequired
  - namestringrequired
  - quantitynumberrequired
  - unitCodestringrequired
  - netPriceCentsnumberrequired
  - netAmountCentsintegerrequired
    -9007199254740991–9007199254740991
  - vatCategorystringrequired
  - vatRatenumber | nullrequired
- vatBreakdownArray<object>required
  - categorystringrequired
  - ratenumber | nullrequired
  - taxableCentsintegerrequired
    -9007199254740991–9007199254740991
  - taxCentsintegerrequired
    -9007199254740991–9007199254740991
  - exemptionReasonstring | nullrequired
- payableCentsinteger | nullrequired
  -9007199254740991–9007199254740991
- validationobject | nullrequired
  - validbooleanrequired
  - errorCountintegerrequired
    -9007199254740991–9007199254740991
  - warningCountintegerrequired
    -9007199254740991–9007199254740991
  - issuesArray<object>required
    at most 50
  - externalobject | nullrequired
    official KoSIT validator
- parserWarningsArray<string>required
- extensionobject | nullrequired
  XRechnung extension: fully preserved, display to follow (ER-10)
  - subLineCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentCountintegerrequired
    -9007199254740991–9007199254740991
  - thirdPartyPaymentsCentsintegerrequired
    -9007199254740991–9007199254740991
- xmlobject | nullrequired
  Original XML (archived, § 147 AO)
  - source"original" | "extracted"required
    original = uploaded XML file, extracted = taken from the PDF
  - sha256stringrequired
  - sizeintegerrequired
    -9007199254740991–9007199254740991
  - archiveRecordIdstring | nullrequired
ocrReceiptOcrrequired
- status"pending" | "running" | "done" | "failed" | "skipped"required
- enginestring | nullrequired
  gemini-… (OCR) or einvoice (structured e-invoice)
- confidencenumber | nullrequired
  0–1
- errorstring | nullrequired
- attemptsintegerrequired
  -9007199254740991–9007199254740991
- processedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
duplicateOfstring | nullrequired
ID of a possibly identical receipt
emailobject | nullrequired
Origin when received by email
- fromstringrequired
- subjectstringrequired
- receivedAtstring (date-time)required
  Timestamp (ISO 8601)
importobject | nullrequired
- providerstringrequired
- jobIdstringrequired
- rowintegerrequired
  -9007199254740991–9007199254740991
lockedbooleanrequired
bookedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 413, 415, 429, 500

curl

curl -X POST 'https://www.debt-flow.io/api/v1/receipts/photos' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file' \
  -F 'notes=…' \
  -F 'capturedAt=…'

Response 202

{
  "id": "string",
  "object": "receipt",
  "status": "inbox",
  "source": "upload",
  "number": "string",
  "file": {
    "fileName": "string",
    "contentType": "string",
    "size": 0,
    "sha256": "string"
  },
  "supplierContactId": "string",
  "supplierName": "string",
  "supplierVatId": "string",
  "supplierIban": "string",
  "documentNumber": "string",
  "documentDate": "2026-11-01",
  "dueDate": "2026-11-01",
  "currency": "EUR",
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0
  },
  "taxLines": [
    {
      "taxRate": 0,
      "netCents": 0,
      "taxCents": 0
    }
  ],
  "taxTreatment": "regular",
  "category": "goods",
  "postingFacts": {
    "softwareKind": "subscription",
    "durableAsset": false,
    "businessEntertainment": false,
    "giftValuePerRecipientCents": 0,
    "giftRecipients": "string",
    "travelKind": "fares"
  },
  "accounts": {
    "skr03": "string",
    "skr04": "string"
  },
  "description": "string",
  "notes": "string",
  "paymentStatus": "open",
  "paidAt": "2026-11-01",
  "bankTransactionId": "string",
  "einvoice": {
    "format": "zugferd",
    "profile": "string",
    "formatLabel": "string",
    "typeCode": "string",
    "number": "string",
    "currency": "string",
    "lineCount": 0,
    "lines": [
      {
        "id": null,
        "name": null,
        "quantity": null,
        "unitCode": null,
        "netPriceCents": null,
        "netAmountCents": null,
        "vatCategory": null,
        "vatRate": null
      }
    ],
    "vatBreakdown": [
      {
        "category": null,
        "rate": null,
        "taxableCents": null,
        "taxCents": null,
        "exemptionReason": null
      }
    ],
    "payableCents": 0,
    "validation": {
      "valid": null,
      "errorCount": null,
      "warningCount": null,
      "issues": null,
      "external": null
    },
    "parserWarnings": [
      "string"
    ],
    "extension": {
      "subLineCount": null,
      "thirdPartyPaymentCount": null,
      "thirdPartyPaymentsCents": null
    },
    "xml": {
      "source": null,
      "sha256": null,
      "size": null,
      "archiveRecordId": null
    }
  },
  "ocr": {
    "status": "pending",
    "engine": "string",
    "confidence": 0,
    "error": "string",
    "attempts": 0,
    "processedAt": "2026-11-01T09:30:00.000Z"
  },
  "duplicateOf": "string",
  "email": {
    "from": "string",
    "subject": "string",
    "receivedAt": "2026-11-01T09:30:00.000Z"
  },
  "import": {
    "provider": "string",
    "jobId": "string",
    "row": 0
  },
  "locked": false,
  "bookedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}