# 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**.
1. Enter a name for the client, choose an Access Level and when the token expires, and select **Create token**.
1. Copy the token. The page shows it once.
1. Send the token in the `Authorization` header of each request:

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

The [OpenAPI document](/api/v1/openapi.json) describes every endpoint, field and response, and needs no token. This page is also available as [Markdown](/docs/user-api.md), 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](#categorisation-rules) 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](#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`.

```bash
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:

```json
{
  "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.

```bash
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.

```bash
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:

```json
{
  "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.

```bash
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.
