evenbooks
Sign inStart for free

Imports

Importing history from another app.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

List ledger imports

get/imports/ledger

The 100 most recent, newest first, without their accounts and entries.

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Upload a general ledger CSV

post/imports/ledger
Administrator keyWrite access

Administrators only. Step 1 of importing history from another accounting app: stores the file, detects its columns (Wave exports are recognized) and returns a previewed import with each source account and the entries found. Nothing is posted yet: set columns and accounts with PATCH /imports/ledger/{id}, then POST /imports/ledger/{id}/commit.

Request body

CreateLedgerImportInput

  • fileNamestringrequired

    1–255 characters

  • contentstringrequired

    1–10485760 characters

Response 200

LedgerImportDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get a ledger import

get/imports/ledger/{id}

A previewed import is analyzed again against the current accounts, entries and closed periods, with its source accounts and entries (problems first, capped).

Parameters

  • idstring (uuid)path · required

Response 200

LedgerImportDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Change a ledger import

patch/imports/ledger/{id}
Administrator keyWrite access

Administrators only. Set the column mapping, map source account names to Evenbooks accounts (accountMap, merged into the saved map; null clears one), or set cash-basis amounts per settlement (cashOverrides; a new mapping clears them). Only while previewed (409 invalid_state). Returns the new preview.

Parameters

  • idstring (uuid)path · required

Request body

UpdateLedgerImportInput

Response 200

LedgerImportDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Post a ledger import

post/imports/ledger/{id}/commit
Administrator keyWrite accessIdempotent

Administrators only. Posts every ready entry as a journal entry, in date order; entries with errors (including those dated in a closed period) and duplicates are skipped and counted. Every source account the ready entries use must be mapped, and every settlement that needs a cash-basis review must have one (400 validation). Refused when the same file was imported before (409 duplicate). An import already committed is returned unchanged. Idempotent with idempotencyKey.

Parameters

  • idstring (uuid)path · required

Request body

CommitLedgerImportInput

Response 200

LedgerImportDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Discard a ledger import

post/imports/ledger/{id}/discard
Administrator keyWrite access

Administrators only. Only while previewed (409 invalid_state); entries already imported are reversed one by one from the journal instead. Returns no content.

Parameters

  • idstring (uuid)path · required

Response 204

Done; no body

No body.

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

CsvColumnName

string

up to 200 characters

DecimalString

decimal string

string

up to 32 characters · pattern ^-?\d+(\.\d+)?$

IdempotencyKey

string

8–128 characters

ImportCashComponentInput

ImportCashComponentInputOutput

LedgerCsvMapping

LedgerCsvMappingInput

LedgerImportAccountDto

  • sourcestring
  • lineCountinteger
  • debitTotalstring · DecimalString
  • creditTotalstring · DecimalString
  • accountIdstring or null
  • problemstring or null

LedgerImportDto

  • idstring
  • fileNamestring
  • statusstring

    One of: previewed committed discarded

  • mappingLedgerCsvMapping or null
  • rowCountinteger
  • entryCountinteger
  • readyCountinteger
  • importedCountinteger
  • duplicateCountinteger
  • errorCountinteger
  • windowStartstring · PlainDateString or null
  • windowEndstring · PlainDateString or null
  • createdAtstring
  • committedAtstring or null
  • headersarray of stringoptional
  • recognizedFormatstring or nulloptional

    One of: wave_transactions wave_ledger

  • alreadyCommittedbooleanoptional
  • accountsarray of LedgerImportAccountDtooptional
  • entriesarray of LedgerImportEntryDtooptional
  • entriesTruncatedbooleanoptional

LedgerImportEntryDto

  • keystring
  • cashKeystring or null
  • cashReviewRequiredboolean
  • cashComponentsarray of ImportCashComponentInputOutput or null
  • rowNosarray of integer
  • datestring · PlainDateString or null
  • descriptionstring
  • referencestring or null
  • statusstring

    One of: ok duplicate error

  • errorstring or null
  • linesarray of object
    Show 5 fields of each item

PlainDateString

string

pattern ^\d{4}-\d{2}-\d{2}$

Uuid

string (uuid)