User API

The User API lets an agent, a script or another application work with your NumeroMoney data. With a token that has Read access it can list your Bank Accounts, Transactions, Categories and CSV Import Formats. With Read and write access it can also import statements, add, categorise and delete Transactions, and manage Categories, Categorisation Rules, Bank Accounts and CSV Import Formats.

The User API reaches only the Bank Accounts you own. Bank Accounts that other people share with you are left out. It needs Pro access: a subscription or the 30 day trial.

Get started

  1. In NumeroMoney, go to Settings > User API Access Tokens.

  2. Enter a name for the client, choose an Access Level and when the token expires, and select Create token.

  3. Copy the token. The page shows it once.

  4. Send the token in the Authorization header of each request:

    curl -H "Authorization: Bearer $NUMEROMONEY_TOKEN" https://www.numeromoney.com/api/v1/bank-accounts
    

The OpenAPI document describes every endpoint, field and response, and needs no token. This page is also available as Markdown, which an agent can read directly.

Access Levels

Access Level What the token can do
Read Call every GET endpoint.
Read and write Call every endpoint on this page.

A token keeps the Access Level it was created with. To change it, create a new token and revoke the old one. A write with a Read token gets 403 write_access_required.

Bank Accounts

Endpoint What it does
GET /api/v1/bank-accounts Lists your Bank Accounts with their currency, timezone and overall budget.
POST /api/v1/bank-accounts Creates a Bank Account.
PATCH /api/v1/bank-accounts/{bankAccountId} Renames a Bank Account, sets its overall budget, or changes its currency or timezone.

A new Bank Account has the same Categories as one created in the application: Income, Transfer, Groceries, Bills and Personal.

Field Rule
name 2 to 100 characters, different from the names of your other Bank Accounts, ignoring case.
currencyCode One of AUD, BHD, CAD, CHF, CNY, EUR, GBP, INR, JPY, KRW, KWD, OMR and USD. Leave it out to use your default currency.
timezone An IANA timezone, such as Europe/London. Leave it out to use your default timezone.
overallBudgetAmount, overallBudgetPeriod Set together: an amount greater than zero, and Monthly or Yearly. Send "overallBudgetAmount": null to remove the budget.

PATCH changes only the fields you send. The currency and timezone cannot change once the Bank Account has Transactions, and the request gets 409 has_transactions.

Transactions

Endpoint What it does
GET /api/v1/bank-accounts/{bankAccountId}/transactions Lists one page of Transactions, newest first.
POST /api/v1/bank-accounts/{bankAccountId}/transactions Adds up to 1,000 Transactions.
PATCH /api/v1/bank-accounts/{bankAccountId}/transactions Sets the note and Splits of up to 500 Transactions.
POST /api/v1/bank-accounts/{bankAccountId}/transactions/delete Deletes up to 500 Transactions.
POST /api/v1/bank-accounts/{bankAccountId}/statement-imports Imports a bank statement file.

The date, description and amount of a Transaction cannot change. To correct one, delete it and add it again.

List Transactions

Parameter Meaning
startDate, endDate Dates as YYYY-MM-DD. endDate includes the whole day.
categoryId Transactions with a Split in this Category.
includeChildCategories With categoryId, also matches the Category's child Categories.
uncategorisedOnly Transactions with no Splits. Cannot be combined with categoryId.
search Text in the description, note or amount, ignoring case.
pageNumber Starts at 1.
pageSize 1 to 500. The default is 100.

The response is { items, pageNumber, pageSize, totalCount }. Each item has an id, the statement date, description and amount, a note, its merchantKey and its splits. A negative amount is money out. An empty splits list means the Transaction is uncategorised.

merchantKey is the part of the description that stays the same from one payment at a merchant to the next. It is the description's first 18 characters, upper case, without the words that contain a digit, so AMAZON* XY12Z3456 LONDON and AMAZON* AB98C7654 LONDON both have the key AMAZON. The marketplace's other spellings, such as AMZNMktplace*, share that key, and AMAZON PRIME keeps its own. It is null when that leaves fewer than three letters, as it does for most transfers between accounts.

An uncategorised Transaction can also have a suggestion:

Field Meaning
categoryId The suggested Category. suggestedCategoryId repeats it, for clients written before suggestion.
source rule: a Categorisation Rule matched. description: earlier Transactions in this Bank Account with the same description, ignoring case and runs of spaces. merchant: earlier Transactions with the same merchantKey.
confidence The share of the earlier Transactions counted that are in the Category, from 0.6 to 1. Always 1 for a rule.
basedOn How many earlier Transactions were counted. 0 for a rule.
ruleId The rule that matched, when source is rule.

A suggestion comes from the first of these that gives one: a rule, then the same description, then the same merchantKey. When there are earlier Transactions with the same description, the merchantKey is not used. History gives a suggestion only when one Category holds at least 0.6 of the earlier Transactions counted, so a merchant whose Transactions are spread across many Categories gets none, and neither does a tie. When at least three earlier Transactions have the same sign and an amount between half and double this one's, only those are counted, because one merchant can mean different things at different amounts. The history is the Bank Account's 10,000 most recent Category uses.

To apply the suggestions you trust, send their categoryId back in Categorise Transactions.

Add Transactions

Send the Transactions in statement order. Each has a date (YYYY-MM-DD), a description of up to 500 characters, a non-zero amount, and an optional note.

curl -X POST "https://www.numeromoney.com/api/v1/bank-accounts/$BANK_ACCOUNT_ID/transactions" \
  -H "Authorization: Bearer $NUMEROMONEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      { "date": "2026-03-02", "description": "Garden Centre", "amount": -12.50, "note": "Seeds" },
      { "date": "2026-03-03", "description": "Acme Ltd", "amount": 1500.00 }
    ]
  }'

The response lists what was added and what was skipped:

{
  "addedCount": 2,
  "duplicateCount": 0,
  "categorisedCount": 0,
  "added": [ { "id": "...", "date": "2026-03-02", "description": "Garden Centre", "amount": -12.50, "note": "Seeds", "splits": [] } ],
  "duplicates": []
}

Each added Transaction that a Categorisation Rule matches is put in the rule's Category as one Split of the whole amount, and categorisedCount says how many. Suggestions from history are not applied.

Import a statement file

Send the file as multipart/form-data in a field named file, up to 5 MB. A file that contains <OFX> or OFXHEADER is read as OFX, which covers OFX, QFX and QBO files. Any other file is read as CSV, and needs csvImportFormatId: the id of one of your CSV Import Formats.

curl -X POST "https://www.numeromoney.com/api/v1/bank-accounts/$BANK_ACCOUNT_ID/statement-imports" \
  -H "Authorization: Bearer $NUMEROMONEY_TOKEN" \
  -F "file=@statement.csv" \
  -F "csvImportFormatId=$CSV_IMPORT_FORMAT_ID"

The response has the same shape as adding Transactions. A row that does not match the CSV Import Format, such as a date in another format, fails the whole import with 422 validation_failed and a message that quotes the value.

Duplicates

Adding Transactions and importing a statement both skip Duplicates: Transactions with the same date, description and amount as one the Bank Account already has. The response lists each Duplicate with its position in the request or the file, starting at 0.

Each Transaction the Bank Account already has accounts for one identical Transaction in the request. If the Bank Account has one coffee for 3.20 on a day and the request has two, one is skipped and one is added. Identical Transactions within one request or one file are all added. Sending the same request again adds nothing.

Categorise Transactions

Each item names a Transaction id, and can set note, splits or both. A field you leave out stays as it is.

  • "note": null removes the note.
  • splits replaces all of the Transaction's Splits. Each Split has a categoryId of the same Bank Account, an amount, and an optional note.
  • The Split amounts must add up exactly to the Transaction's amount.
  • "splits": [] makes the Transaction uncategorised.
curl -X PATCH "https://www.numeromoney.com/api/v1/bank-accounts/$BANK_ACCOUNT_ID/transactions" \
  -H "Authorization: Bearer $NUMEROMONEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "id": "'"$TRANSACTION_ID"'",
        "splits": [
          { "categoryId": "'"$PLANTS_CATEGORY_ID"'", "amount": -8.50, "note": "Roses" },
          { "categoryId": "'"$TOOLS_CATEGORY_ID"'", "amount": -4.00 }
        ]
      }
    ]
  }'

The response lists each Transaction as it is after the change. If any item is not valid, no Transaction changes, and the response lists every problem by the item's position:

{
  "error": "validation_failed",
  "message": "1 item failed validation, so nothing was changed. See items.",
  "items": [ { "index": 0, "message": "The Splits add up to -12.00, and must add up to the Transaction's amount, -12.5." } ]
}

Delete Transactions

Send { "ids": [...] }. The response has deletedCount, the deleted ids, and the notFound ids: ids the Bank Account does not have, for example because an earlier attempt of the same request deleted them.

Categories

Endpoint What it does
GET /api/v1/bank-accounts/{bankAccountId}/categories Lists the Bank Account's Categories, with parents and budgets.
POST /api/v1/bank-accounts/{bankAccountId}/categories Creates a Category.
PATCH /api/v1/bank-accounts/{bankAccountId}/categories/{categoryId} Changes a Category that you created.
DELETE /api/v1/bank-accounts/{bankAccountId}/categories/{categoryId} Deletes a Category that you created, and its child Categories.
Field Rule
name Up to 35 characters, different from the Bank Account's other Category names, ignoring case.
parentId A top-level Category of the same Bank Account. A Category with child Categories cannot have a parent.
isTransfer, isIncome A Category cannot be both. A child Category has the same values as its parent: leave them out when you create one, and it takes its parent's values.
budgetAmount, budgetPeriod Set together: an amount greater than zero, and Monthly or Yearly. Transfer and income Categories have no budget.

PATCH changes only the fields you send, and null removes a parent or a budget. Changing isTransfer or isIncome on a parent changes its child Categories too, and removes their budgets.

A Category that a Transaction uses, directly or through a child Category, cannot be deleted. The request gets 409 category_in_use, with the number of Transactions in transactionCount. Change those Transactions' Splits first.

Categorisation Rules

Endpoint What it does
GET /api/v1/bank-accounts/{bankAccountId}/categorisation-rules Lists the Bank Account's rules in the order they are tried.
POST /api/v1/bank-accounts/{bankAccountId}/categorisation-rules Creates a rule.
PATCH /api/v1/bank-accounts/{bankAccountId}/categorisation-rules/{ruleId} Changes a rule.
DELETE /api/v1/bank-accounts/{bankAccountId}/categorisation-rules/{ruleId} Deletes a rule. The Transactions it categorised keep their Splits.
POST /api/v1/bank-accounts/{bankAccountId}/categorisation-rules/preview Lists the uncategorised Transactions that the rules would categorise, and changes nothing. A Read token can call it.
POST /api/v1/bank-accounts/{bankAccountId}/categorisation-rules/apply Categorises the uncategorised Transactions that the saved rules match.

A Categorisation Rule puts the Transactions it matches in one Category of the Bank Account. Statement Imports and added Transactions apply the rules as they arrive, and a rule's Category is also the suggestion for an uncategorised Transaction it matches.

Field Rule
matchType merchant_key: the Transaction's merchantKey equals matchText. contains: the description contains matchText. starts_with: the description starts with matchText. All three ignore case and treat a run of spaces as one space.
matchText 1 to 100 characters. A merchant_key text has no digits, because a key never has any.
categoryId A Category of the same Bank Account.
amountMin, amountMax Optional signed limits, both inclusive. -20 to 0 matches money out of up to 20.
position Rules are tried from the lowest position, and equal positions oldest first. The first rule that matches wins. Leave it out to put a new rule after the others.

PATCH changes only the fields you send, and null removes an amount limit. Deleting the Category deletes its rules.

curl -X POST "https://www.numeromoney.com/api/v1/bank-accounts/$BANK_ACCOUNT_ID/categorisation-rules" \
  -H "Authorization: Bearer $NUMEROMONEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "matchType": "merchant_key", "matchText": "TOWN COUNCIL", "categoryId": "'"$PARKING_CATEGORY_ID"'", "amountMin": -20, "amountMax": 0 }'

To see what a rule would do before you save it, send it to preview as { "rule": { ... } }. Send {} to preview the saved rules. Both preview and apply return { count, items }, where each item has the transaction, the categoryId and categoryName it gets, and the ruleId that matched, which is null for an unsaved rule. apply records each Transaction it changes in the User API Change Log.

CSV Import Formats

Endpoint What it does
GET /api/v1/csv-import-formats Lists your CSV Import Formats, and the Bank Accounts that used each one.
POST /api/v1/csv-import-formats Creates a CSV Import Format.
PATCH /api/v1/csv-import-formats/{csvImportFormatId} Renames a CSV Import Format.
DELETE /api/v1/csv-import-formats/{csvImportFormatId} Deletes a CSV Import Format. Transactions imported with it stay.

A CSV Import Format has a name of up to 100 characters, different from your other formats ignoring case, amountsReversed, and columnMappings. Column positions start at 0.

Column mapping Rule
dateColumnIndex Required.
dateFormat A .NET date format, such as dd/MM/yyyy. Leave it out to detect the format on import.
descriptionColumnIndex Required.
amountColumnIndex The amount column, or -1 when the file has separate debit and credit columns.
debitColumnIndex, creditColumnIndex Set together. When both are set, an amount is the credit minus the debit.
amountTypeColumnIndex A column that marks each amount as D or DEBIT, or C or CREDIT.
noteColumnIndex A column to import as each Transaction's note.
hasHeaderRow true by default. Set it to false for a file whose first row is a Transaction, not column names.

Set amountsReversed to true for a statement that shows money out as a positive number. Only the name of a CSV Import Format can change. For different columns, create a new one.

User API Change Log

NumeroMoney records every change that a token makes: the token, the time, the record, and its values before and after the change. One request's changes share a request id. A request that fails changes nothing and records nothing.

You can read the log in Settings > User API Change Log, for all tokens or for one. Entries stay after you revoke a token. They are deleted after 365 days, when you delete the Bank Account they belong to, or when you delete your account.

Retries

A request that changes data either completes or changes nothing. If a request times out, you can send it again:

  • Adding Transactions and importing a statement skip the Transactions the first attempt added, as Duplicates.
  • Setting notes and Splits gives the same result again.
  • Deleting Transactions lists the ones the first attempt deleted as notFound.
  • Creating a Bank Account, Category or CSV Import Format with a name you already have gets 409 duplicate_name, so a retry does not make a copy.

When two requests change the same record, the later one wins.

Errors

Every error is JSON in the form { "error": "<code>", "message": "<text>" }.

Status error When
400 invalid_request The request cannot be read, such as JSON with a field of the wrong type.
401 invalid_token The token is missing, unknown or revoked.
401 token_expired The token has expired.
403 pro_required You have no Pro access. Tokens work again as soon as Pro access returns.
403 write_access_required The token's Access Level is Read, and the request changes data.
403 not_creator Another person who shares the Bank Account created the Category.
404 not_found The endpoint does not exist, or you do not own the Bank Account or record.
405 method_not_allowed The endpoint does not accept this method.
409 duplicate_name You already have a record with this name.
409 has_transactions The Bank Account's currency or timezone cannot change because it has Transactions.
409 category_in_use A Transaction has a Split in the Category or its child Categories.
422 validation_failed A value breaks a rule. For a request with many items, items lists each problem by position.
429 rate_limited The token has used its 60 requests for this minute. The Retry-After header gives the wait in seconds.
500 internal_error An unexpected failure.

Limits

  • Each token can make 60 requests a minute, counting reads and writes together.
  • You can have 10 tokens that have not expired.
  • A token expires after 30, 90 or 365 days, or never, as you choose when you create it.