Pulling Invoices as JSON

Overview

If you do not need an accounting-program file format, you can read invoices straight from the API as JSON and import them into your own system. Parseo tracks which invoices have been exported, so you never have to remember that yourself:

• GET /invoices?exported=false is your queue: invoices nobody has exported yet.
• POST /invoices/{id}/exported marks an invoice as exported, after your import succeeded.
• export.changedSinceExport tells you an invoice was corrected after you took it.

Fetching an invoice never marks it. A retry, a preview or an import that fails halfway leaves the invoice in the queue. Only your acknowledgement removes it.

The acknowledgement endpoints need the invoice:export scope.

The export block

Every invoice carries an export object:

"export": {
  "exported": true,
  "exportCount": 1,
  "lastExportedAt": "2026-10-16T09:12:00.000Z",
  "externalReference": "ERP-2026-00412",
  "changedSinceExport": false
}

The loop

1. Find work. Subscribe to the invoice.processed webhook, or poll:

curl "https://app.parseo.app/external/v1/invoices?status=processed&isExportValid=true&exported=false" \
  -H "Authorization: Bearer parseo_live_..."

The list omits line items. Fetch each invoice for its full content:

curl https://app.parseo.app/external/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer parseo_live_..."

On a team with AI fields enabled, a polled invoice can read processed while its AI-filled custom fields are still being written (usually seconds, longer while many invoices queue for that step), and that write fires no invoice.updated. The invoice.processed webhook waits for it, so an export fetched after the webhook includes those values; prefer the webhook there. See Webhooks.

2. Import it into your own system.

If the document states a delivery address, deliveryAddress carries it as one unstructured string, separate from buyer.address. It is null when the document states none.

Each line item carries its unit of measure twice. unit is the text printed on the document (vnt, kg, dėžė), and unitCode is a standard code you can map to your own units: pcs, kg, l, hrs, m, t, m2, m3, km or pak. unitCode is null when Parseo does not recognise the printed unit; map those from unit. Both describe quantity and unitPrice as printed. Parseo never converts them.

3. Acknowledge it, optionally with the id your system gave the document:

curl -X POST https://app.parseo.app/external/v1/invoices/inv_abc123/exported \
  -H "Authorization: Bearer parseo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalReference": "ERP-2026-00412" }'

Or acknowledge up to 100 at once. The response is 207 with a result per invoice:

curl -X POST https://app.parseo.app/external/v1/invoices/bulk/mark-exported \
  -H "Authorization: Bearer parseo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "id": "inv_abc123", "externalReference": "ERP-1" }, { "id": "inv_def456" } ] }'

Acknowledging is safe to repeat. A second call for an unchanged invoice records nothing new.

Acknowledged invoices drop out of an exported=false query. When you drain the queue, start again from the first page after acknowledging a page rather than following nextCursor.

Corrections after export

Someone may correct an invoice in Parseo after you imported it. When that happens, export.changedSinceExport becomes true and an invoice.updated webhook fires. To find these invoices by polling:

curl "https://app.parseo.app/external/v1/invoices?changedSinceExport=true" \
  -H "Authorization: Bearer parseo_live_..."

Re-import the invoice (update the document you created, using your externalReference), then acknowledge it again. That records a new export and clears the flag.

changedSinceExport reacts to any modification of the invoice after export, including ones Parseo makes itself, such as re-validation. Treat it as a signal to re-fetch and compare, not as proof that the amounts changed.

Undoing an acknowledgement

If your import rolled back, put the invoice back in the queue:

curl -X DELETE https://app.parseo.app/external/v1/invoices/inv_abc123/exported \
  -H "Authorization: Bearer parseo_live_..."

This clears the export state recorded by any path, including a dashboard export.

One flag per invoice

Exported state is shared. If the same team also exports invoices from the dashboard or pushes them to an accounting system, those invoices count as exported here too. If two of your systems both need to pull the same invoices, contact us before building on this.