LumaLedger
Sign inGet started
Developers
API reference

Imports

get/v1/imports

List imports

imports.listread tokenidempotent

The files imported into this ledger, newest first: bank exports, OFX statements, Rocket Money exports and the app's Chase importer.

Parameters

limit
integer · query
Page size, 1–200.
cursor
string | null · query
The next_cursor of the previous page.
account_id
integer | null · query
Only imports into this account.
X-Organization-Id
string | null · header

Returns 200 · ImportList

data
array of Import · required
has_more
boolean · required
next_cursor
string | null · required
Example
curl -X GET "https://api.lumaledger.app/v1/imports" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
post/v1/imports

Import a file

imports.createwrite tokenidempotent

Import a bank's export into an account and settle the ledger: transfers are matched, transactions categorized, your rules applied and everything posted. Answers 202 with a Job (kind import); poll jobs.get. Its result: import_id (see imports.list), row_count, new_count, duplicate_count (rows already in the ledger, skipped) and journals_posted. Importing the same file twice is harmless: its rows come back as duplicates. Send the file as content, or upload it with files.create and send its file_id. Send an Idempotency-Key so a retry cannot start a second job.

Parameters

Idempotency-Key
string | null · header
Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id
string | null · header

Body · ImportCreate

account_id
integer · required
The bank, card or loan account the rows belong to (an asset or liability from accounts.list).
content
string | null
The file's text: a CSV, or an OFX / QFX statement. At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.
filename
string | null
Shown in the import history. Defaults to the uploaded file's name.
mapping
ImportMapping | null
How to read a CSV (from imports.preview). Required for a CSV, ignored for an OFX / QFX statement.

Returns 202 · Job

created_at
datetime · required
error
JobError | null · required
Why it failed, once failed.
finished_at
datetime | null · required
id
integer · required
kind
string · required
What the job does: import, categorize, generate_journals, reconcile, run_schedules, plaid_sync or rocket_money_import.
result
object | null · required
What the work produced, once succeeded. Its fields depend on kind and are listed on the operation that started it. Counts are integers.
status
string · required
queued, running, succeeded or failed.
Example
curl -X POST "https://api.lumaledger.app/v1/imports" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1
  }'
post/v1/imports/preview

Preview a file before importing it

imports.previewread tokenidempotent

Read a bank's export and say how it would be imported, writing nothing: its columns, its first rows, a guessed mapping, and the saved_mapping the account used last time for the same header. Check or correct the mapping, then send it to imports.create. An OFX / QFX statement needs no mapping (format is ofx). Send the file as content, or upload it with files.create and send its file_id.

Parameters

X-Organization-Id
string | null · header

Body · ImportPreviewRequest

account_id
integer | null
The account the file is for. Given, the preview includes the mapping this account last imported a file with the same header with.
content
string | null
The file's text: a CSV, or an OFX / QFX statement. At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.

Returns 200 · ImportPreview

columns
array of string · required
The file's column names, or the OFX fields a transaction has.
date_formats
array of string · required
The formats mapping.date_format may take.
format
string · required
csv or ofx. An OFX file needs no mapping.
mapping
ImportMapping | null · required
Our reading of the columns; null when nothing plausible fits.
ofx
OfxStatementInfo | null · required
rows
array of array of string · required
The first rows, cell for cell, in columns order.
saved_at
datetime | null · required
saved_mapping
ImportMapping | null · required
The mapping this account last used for a file with this header, when account_id was sent and there is one. Import with it as it is.
total_rows
integer · required
Example
curl -X POST "https://api.lumaledger.app/v1/imports/preview" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/imports/rocket-money

Import a Rocket Money export

imports.create_rocket_moneywrite tokenidempotent

Switch from Rocket Money: create the accounts its export names that the ledger does not have, import each account's transactions, and settle the ledger. Answers 202 with a Job (kind rocket_money_import); poll jobs.get. Its result: accounts_created, accounts_used, row_count, new_count, duplicate_count and journals_posted. Importing the same export twice is harmless: the second time finds the accounts it made and every row a duplicate. Send an Idempotency-Key so a retry cannot start a second job.

Parameters

Idempotency-Key
string | null · header
Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id
string | null · header

Body · RocketMoneyImportCreate

content
string | null
The export's text (Rocket Money's "Export transactions" CSV). At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.
filename
string | null
Shown in the import history. Defaults to the uploaded file's name.
plan
array of RocketMoneyPlanStep
Changes to the preview, per account. Empty: import as previewed.

Returns 202 · Job

created_at
datetime · required
error
JobError | null · required
Why it failed, once failed.
finished_at
datetime | null · required
id
integer · required
kind
string · required
What the job does: import, categorize, generate_journals, reconcile, run_schedules, plaid_sync or rocket_money_import.
result
object | null · required
What the work produced, once succeeded. Its fields depend on kind and are listed on the operation that started it. Counts are integers.
status
string · required
queued, running, succeeded or failed.
Example
curl -X POST "https://api.lumaledger.app/v1/imports/rocket-money" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
post/v1/imports/rocket-money/preview

Preview a Rocket Money export

imports.preview_rocket_moneyread tokenidempotent

Read a Rocket Money export (one CSV for every account) and say what importing it would do, writing nothing: each account it names, how many transactions, and the ledger account its rows would go into, or that a new one would be created. Adjust with a plan, then send it to imports.create_rocket_money.

Parameters

X-Organization-Id
string | null · header

Body · RocketMoneyPreviewRequest

content
string | null
The export's text (Rocket Money's "Export transactions" CSV). At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.

Returns 200 · RocketMoneyPreview

accounts
array of RocketMoneyAccount · required
kinds
array of string · required
The kinds a new account may be given in plan.
outflow_is_positive
boolean · required
The file writes money out as positive amounts (Rocket Money's way), read off its income rows. Informational: the import already accounts for it.
total_rows
integer · required
Example
curl -X POST "https://api.lumaledger.app/v1/imports/rocket-money/preview" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

Import

One file imported into one account.

Fields

account_id
integer · required
The account its rows were written into.
created_at
datetime · required
duplicate_count
integer · required
Rows skipped because they were already in the ledger.
filename
string · required
id
integer · required
new_count
integer · required
Rows written as new transactions.
row_count
integer · required
Rows in the file.
source
string · required
What read it: csv, ofx, chase_checking, rocket_money, …
status
string · required

ImportCreate

Fields

account_id
integer · required
The bank, card or loan account the rows belong to (an asset or liability from accounts.list).
content
string | null
The file's text: a CSV, or an OFX / QFX statement. At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.
filename
string | null
Shown in the import history. Defaults to the uploaded file's name.
mapping
ImportMapping | null
How to read a CSV (from imports.preview). Required for a CSV, ignored for an OFX / QFX statement.

ImportList

A page of imports, newest first.

Fields

data
array of Import · required
has_more
boolean · required
next_cursor
string | null · required

ImportMapping

Which column is which. A CSV has either one amount_column or a debit_column and a credit_column.

Fields

amount_column
string | null
balance_column
string | null
The running balance after each row.
category_column
string | null
credit_column
string | null
Money in, when the file splits the two.
date_column
string · required
date_format
string
A strptime format, one of date_formats in the preview. Default: "%Y-%m-%d".
debit_column
string | null
Money out, when the file splits the two.
decimal_comma
boolean
Amounts are written 1.234,56. Default: false.
description_column
string · required
outflow_is_positive
boolean
With one amount_column: money out is written as a positive number. Default: false.

ImportPreview

Fields

columns
array of string · required
The file's column names, or the OFX fields a transaction has.
date_formats
array of string · required
The formats mapping.date_format may take.
format
string · required
csv or ofx. An OFX file needs no mapping.
mapping
ImportMapping | null · required
Our reading of the columns; null when nothing plausible fits.
ofx
OfxStatementInfo | null · required
rows
array of array of string · required
The first rows, cell for cell, in columns order.
saved_at
datetime | null · required
saved_mapping
ImportMapping | null · required
The mapping this account last used for a file with this header, when account_id was sent and there is one. Import with it as it is.
total_rows
integer · required

ImportPreviewRequest

Fields

account_id
integer | null
The account the file is for. Given, the preview includes the mapping this account last imported a file with the same header with.
content
string | null
The file's text: a CSV, or an OFX / QFX statement. At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.

Job

Work that outlives the request that started it. Poll jobs.get until status is succeeded or failed.

Fields

created_at
datetime · required
error
JobError | null · required
Why it failed, once failed.
finished_at
datetime | null · required
id
integer · required
kind
string · required
What the job does: import, categorize, generate_journals, reconcile, run_schedules, plaid_sync or rocket_money_import.
result
object | null · required
What the work produced, once succeeded. Its fields depend on kind and are listed on the operation that started it. Counts are integers.
status
string · required
queued, running, succeeded or failed.

JobError

Fields

code
string · required
Stable error code, as in the error envelope.
message
string · required
For people, in the request's language. Never match on it.

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount
string · required
Pattern: ^-?\d+\.\d{2}$.
currency
string · required
ISO 4217 code. Pattern: ^[A-Z]{3}$.

OfxStatementInfo

What an OFX / QFX statement says about itself: check it is the right account before importing.

Fields

account_last4
string | null · required
account_type
string | null · required
The file's own word: CHECKING, SAVINGS, CREDITLINE, …
balance
Money | null · required
The statement's closing balance, in the statement's currency.
balance_date
date | null · required
currency
string | null · required
from_date
date | null · required
to_date
date | null · required

RocketMoneyAccount

One account the export names, and what it would be imported into.

Fields

account_type
string | null · required
The file's own words for the account (Credit Card).
existing_account_id
integer | null · required
An account already in the ledger that looks like this one (same name, same side of the balance sheet, same bank when it says one). Its rows go there unless plan says otherwise. Null: a new account is created.
existing_account_name
string | null · required
from_date
date · required
institution
string · required
key
string · required
Names this account in plan when importing. Opaque.
kind
string · required
What a new account would be made as, read off account_type: one of kinds. Overrule it in plan.
mask
string | null · required
The account number's last digits, when the file has them.
name
string · required
row_count
integer · required
Transactions in the file for this account.
to_date
date · required

RocketMoneyImportCreate

Fields

content
string | null
The export's text (Rocket Money's "Export transactions" CSV). At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.
filename
string | null
Shown in the import history. Defaults to the uploaded file's name.
plan
array of RocketMoneyPlanStep
Changes to the preview, per account. Empty: import as previewed.

RocketMoneyPlanStep

What to do with one of the export's accounts. An account left out of the plan is imported as previewed.

Fields

account_id
integer | null
Import its rows into this ledger account (an asset or liability from accounts.list) instead of the previewed one.
key
string · required
The account's key from imports.preview_rocket_money.
kind
string | null
When a new account is created: what it is, one of the preview's kinds.
skip
boolean
Leave this account's rows out. Default: false.

RocketMoneyPreview

Fields

accounts
array of RocketMoneyAccount · required
kinds
array of string · required
The kinds a new account may be given in plan.
outflow_is_positive
boolean · required
The file writes money out as positive amounts (Rocket Money's way), read off its income rows. Informational: the import already accounts for it.
total_rows
integer · required

RocketMoneyPreviewRequest

Fields

content
string | null
The export's text (Rocket Money's "Export transactions" CSV). At most 5 MB. Send this or file_id.
file_id
integer | null
A file uploaded with files.create, instead of content. At most 5 MB.