Evenbead docs
Contents

Receipts

21 operations. All areas

GET/v1/receipts/inbox

The company's private receipt address (forward receipts to it), its sender allow-list and limits

  • Operation getReceiptInbox
  • Scope: read
  • Read
Responses
  • 200 Inbox (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox

Create or change the receipt inbox: on/off and the senders allowed to forward receipts (addresses or @domains). Mail from anyone else waits for review.

  • Operation updateReceiptInbox
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Request body
  • enabled boolean
  • allowed_senders array of string
Responses
  • 200 Inbox (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox/rotate

Give the inbox a new private address; the old one stops working at once (mail to it is refused and listed)

  • Operation rotateReceiptInbox
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • reason string
Responses
  • 200 Inbox with its new address (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/receipts/inbox/slug

Is a custom receipt name available? receipts+<slug>@... (first come, first served; reserved names and lookalikes refused). Rate-limited.

  • Operation checkReceiptSlug
  • Scope: read
  • Read
Parameters
  • slug query, string, required
Responses
  • 200 Availability (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox/slug

Set the inbox's custom name receipts+<slug>@... (admin; a firm admin may set it for a client). The previous name forwards for 30 days, then is released. The private token address keeps working.

  • Operation setReceiptSlug
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Request body
  • slug string, required 3-30 lower-case letters, digits and single hyphens, starting and ending with a letter or digit; reserved names and lookalikes are refused
Responses
  • 200 Inbox (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox/slug/clear

Remove the custom name; it forwards for 30 days, then is released (admin)

  • Operation clearReceiptSlug
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Request body
  • reason string
Responses
  • 200 Inbox (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/receipts/inbox/messages

Messages the receipt inbox received: processed, waiting for review (unknown sender, failed authentication), quarantined, refused

  • Operation listInboxMessages
  • Scope: read
  • Read
Parameters
  • status query, "processed" | "review" | "quarantined" | "rejected" | "duplicate" | "released" | "discarded" | "expired"
  • limit query, integer
Responses
  • 200 Messages (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox/messages/{id}/release

Process a message that waits for review (a person only): its receipts are stored; optionally allow its sender from now on

  • Operation releaseInboxMessage
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • allow_sender boolean
Responses
  • 200 Released (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/inbox/messages/{id}/discard

Discard a message that waits for review (nothing is processed)

  • Operation discardInboxMessage
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string
Responses
  • 200 Discarded (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/receipts

Receipts, newest first, with what was read from them and their status

  • Operation listReceipts
  • Scope: read
  • Read
Parameters
  • status query, "new" | "extracted" | "matched" | "posted" | "discarded"
  • source query, "email" | "upload" | "camera"
  • limit query, integer
Responses
  • 200 Receipts (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/receipts

Upload a receipt (PDF, JPEG, PNG or HEIC, at most 20 MB, base64). Stored encrypted; the same file twice is the same receipt. A PDF's text is read at once.

  • Operation uploadReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • file_name string, required
  • content_base64 string, required
  • source "upload" | "camera"
  • note string
Responses
  • 201 Stored (created: false when this file was already a receipt) (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/receipts/{id}

One receipt with the bank lines it could match (amount, date window, vendor; with reasons)

  • Operation getReceipt
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Receipt (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}

Correct what was read from a receipt (vendor, date, total, tax, subtotal, payment method) or its note; the corrected facts drive matching

  • Operation updateReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • vendor string | null
  • date string | null Calendar date, YYYY-MM-DD.
  • total_cents integer | null
  • tax_cents integer | null
  • subtotal_cents integer | null
  • payment_method "cash" | "card" | "other" | null
  • note string
Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/receipts/{id}/file

The stored file (decrypted), or an HTML receipt's PDF snapshot (variant=snapshot); format=base64 returns JSON (MCP)

  • Operation getReceiptFile
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • variant query, "original" | "snapshot"
  • format query, "base64"
Responses
  • 200 The file (its own media type), or JSON with content_base64 when format=base64
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/extract

Read the receipt again with this deployment's extractors (PDF text layer, HTML text; OCR when configured)

  • Operation extractReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/match

Attach the receipt to a bank line (it is posted when the line is)

  • Operation matchReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • bank_line_id string, required
Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/unmatch

Detach the receipt from its bank line

  • Operation unmatchReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/attach

Attach the receipt to a posted document (an expense, check or bill): the document's receipt metadata links to the stored file

  • Operation attachReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • document_id string, required
Responses
  • 200 Attached (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/expense

Record the receipt as an expense with the receipt attached, through the governed path (dry_run previews; an agent's always waits for approval: receipt_review)

  • Operation createExpenseFromReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • payment_account string, required
  • account string, required
  • amount_cents integer
  • doc_date string Calendar date, YYYY-MM-DD.
  • payee_id string
  • memo string
  • class string
  • confidence number
  • soft_lock_override_reason string
  • dry_run boolean
Responses
  • 200 Dry run (object)
  • 201 Posted (object)
  • 202 Waiting for approval (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/discard

Set a receipt aside (not a receipt, a duplicate); restore brings it back

  • Operation discardReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/receipts/{id}/restore

Bring a discarded receipt back

  • Operation restoreReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 200 The receipt (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)