Browse the reference

Receipts (OCR)

16 endpoints

Line items read from receipts, newest purchase first; unit prices are also given per base unit (kg, l, unit).

GET/households/{householdId}/receipt-items

read:receipts

Parameters

Name	In	Required	Description
cursor	query	Optional	-
limit	query	Optional	-
sort	query	Optional	date (default, paged) \| unitPrice \| total
transactionId	query	Optional	-
receiptId	query	Optional	-
dateTo	query	Optional	Purchase day, inclusive (YYYY-MM-DD)
dateFrom	query	Optional	Purchase day, inclusive (YYYY-MM-DD)
merchant	query	Optional	-
q	query	Optional	Matches product name, description and brand; terms are ANDed

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipt-items

Response200 · Success

Unit price of a product over time (per base unit, quantity-weighted per bucket) with the merchants it was bought at.

GET/households/{householdId}/receipt-items/price-history

read:receipts

Parameters

Name	In	Required	Description
merchant	query	Optional	-
dateTo	query	Optional	-
dateFrom	query	Optional	-
bucket	query	Optional	month (default) \| week
q	query	Required	Product to follow, e.g. "manzana"

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipt-items/price-history

Response200 · Success

Per-product summary across receipts: purchases, total spend, quantity-weighted average / min / max / latest unit price over the base unit, where it was bought.

GET/households/{householdId}/receipt-items/summary

read:receipts

Parameters

Name	In	Required	Description
limit	query	Optional	-
sort	query	Optional	spend (default) \| unitPrice \| frequency \| name
dateTo	query	Optional	-
dateFrom	query	Optional	-
merchant	query	Optional	-
q	query	Optional	-

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipt-items/summary

Response200 · Success

List receipts in this household; filter by link state, extraction status, kind, day, amount, merchant, tags or free text; sort by date, amount or merchant.

GET/households/{householdId}/receipts

read:receipts

Parameters

Name	In	Required	Description
cursor	query	Optional	nextCursor of the previous page; only valid for the same sort and dateBasis
limit	query	Optional	-
sort	query	Optional	date_desc (default) \| date_asc \| amount_desc \| amount_asc \| merchant_asc; dates follow dateBasis, ties break on id, receipts without a total or merchant come last
inboxOnly	query	Optional	true = not yet linked to a transaction
linked	query	Optional	true = linked to a transaction, false = still in the tray
transactionId	query	Optional	-
status	query	Optional	Comma-separated: pending, processing, extracted, failed
kind	query	Optional	receipt \| invoice \| product \| other
q	query	Optional	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Optional	Which day the date filters and sorts use: receipt (default; the day printed on it, the upload day until it is read) or upload
dateFrom	query	Optional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Optional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Optional	Inclusive lower bound on the read total, integer cents
amountMax	query	Optional	Inclusive upper bound on the read total, integer cents
merchant	query	Optional	Comma-separated merchant keys (from the facets); any of them
tag	query	Optional	Comma-separated tags; all of them

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipts

Response200 · Success

Upload a receipt image (multipart/form-data); optionally attach it to a transaction

POST/households/{householdId}/receipts

write:receipts

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts \     -F "file=@receipt.jpg"

Response201 · Success

Get a receipt: extraction, normalised line items and pre-signed URLs (300s TTL) for the image.

GET/households/{householdId}/receipts/{receiptId}

read:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipts/{receiptId}

Response200 · Success

Correct what was read (ADR 0111): merchant, date, total, currency, kind, tags, summary merge; items replace. A failed receipt becomes usable this way.

PATCH/households/{householdId}/receipts/{receiptId}

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/receipts/{receiptId}

Response200 · Success

Soft-delete a receipt

DELETE/households/{householdId}/receipts/{receiptId}

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/receipts/{receiptId}

Response204 · No content

Attach an unlinked receipt to an existing transaction (ADR 0108)

POST/households/{householdId}/receipts/{receiptId}/attach

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts/{receiptId}/attach

Response200 · Success

Materialise the receipt into a Transaction. Body fields override the extraction.

POST/households/{householdId}/receipts/{receiptId}/confirm

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts/{receiptId}/confirm

Response200 · Success

Detach a receipt from its transaction; it returns to the tray (ADR 0108)

POST/households/{householdId}/receipts/{receiptId}/detach

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts/{receiptId}/detach

Response200 · Success

The receipt image, served inline (or as a download with ?download=1).

GET/households/{householdId}/receipts/{receiptId}/file

read:receipts

Parameters

Name	In	Required	Description
receiptId	path	Required	-
download	query	Optional	Set to 1 to receive an attachment instead of an inline image.

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipts/{receiptId}/file

Response200 · Success

Read the receipt again (failed or extracted, attached or not). 409 while a read is in progress, or over a manual correction unless force=true. Returns the receipt with status="pending".

POST/households/{householdId}/receipts/{receiptId}/retry

write:receipts

Parameters

Name	In	Required
receiptId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts/{receiptId}/retry

Response200 · Success

How many receipts are unlinked, still being read, or failed (for the receipts page header).

GET/households/{householdId}/receipts/counts

read:receipts

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipts/counts

Response200 · Success

Empty the tray: soft-delete every receipt not linked to a transaction. Returns how many were deleted.

POST/households/{householdId}/receipts/empty-tray

write:receipts

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts/empty-tray

Response200 · Success

Facets of the receipts matching the same filters as the list: total, per-month counts and sums (on dateBasis), top merchants, top tags, status and link split.

GET/households/{householdId}/receipts/facets

read:receipts

Parameters

Name	In	Required	Description
inboxOnly	query	Optional	true = not yet linked to a transaction
linked	query	Optional	true = linked to a transaction, false = still in the tray
transactionId	query	Optional	-
status	query	Optional	Comma-separated: pending, processing, extracted, failed
kind	query	Optional	receipt \| invoice \| product \| other
q	query	Optional	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Optional	Which day the date filters and sorts use: receipt (default; the day printed on it, the upload day until it is read) or upload
dateFrom	query	Optional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Optional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Optional	Inclusive lower bound on the read total, integer cents
amountMax	query	Optional	Inclusive upper bound on the read total, integer cents
merchant	query	Optional	Comma-separated merchant keys (from the facets); any of them
tag	query	Optional	Comma-separated tags; all of them

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/receipts/facets

Response200 · Success