# Edara API v3: Accounts

Read the [guide](../guide.md) first: authentication, paging, errors, rate limits and the shared `PagedResult`, `BatchResult` and `*Reference` shapes.

- `GET /v3/accounts`: Lists accounts.
- `GET /v3/accounts/{id}`: Gets an account by id.
- `GET /v3/accounts/{id}/balance`: Gets account balance.
- `GET /v3/accounts/nodes`: Lists leaf account nodes.

## Endpoints

### `GET /v3/accounts`: Lists accounts.

Operation `GetAccounts` · permission `read:account`

**Query string**: `GetAccountsQuery`

| field | type | default | validation | description |
|---|---|---|---|---|
| `offset` | `int?` | 0 | >= 0 | Number of items to skip before returning results. Defaults to 0. |
| `limit` | `int?` | 100 | 1..1000 (out of range → 400) | Maximum number of items to return. Defaults to 100, maximum 1000. |
| `classificationCode` | `string` |  | Must(value => !string.IsNullOrWhiteSpace(value)) .When(x => x.ClassificationCode != null) | The classification code filter. |
| `type` | `AccountType?` |  | Must(value => !value.HasValue \|\| Enum.IsDefined(typeof(AccountType), value.Value)) | The account type filter. |
| `relatedCustomerCode` | `string` |  | Must(value => !string.IsNullOrWhiteSpace(value)) .When(x => x.RelatedCustomerCode != null) | The related customer code filter. |
| `customerExternalId` | `string` |  | Must(value => !string.IsNullOrWhiteSpace(value)) .When(x => x.CustomerExternalId != null) | The related customer external-id filter. |
| `relatedCustomerId` | `int?` |  | GreaterThan(0) .When(x => x.RelatedCustomerId.HasValue) | The related customer identifier filter. |
| `description` | `string` |  | Must(value => !string.IsNullOrWhiteSpace(value)) .When(x => x.Description != null) | The account description filter. |
| `updateDate` | `DateTime?` |  |  | The updated-after filter. |

**Responses**: OK `PagedResult<AccountResponse>`: Paged list of accounts.

**Notes**

- The list only includes accounts the calling user has data permission for. A user with no account permissions gets an empty list.
- Only active accounts are returned.
- `classificationCode` and `type` are exact matches. `description` is a partial match that finds the text anywhere in the description.
- `relatedCustomerCode`, `customerExternalId` and `relatedCustomerId` return the accounts linked to that customer.
- Text filters are trimmed, and a blank value is treated as no filter.
- `updateDate` returns accounts created or updated strictly after that date and time.
- Results are ordered by classification code. `totalCount` is the number of matching accounts, but it is 0 when `offset` is past the end of the results.
- When nothing matches you get `200` with an empty `items` list.

---

### `GET /v3/accounts/{id}`: Gets an account by id.

Operation `GetAccountById` · permission `read:account`

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `id` | route | `int` |  | The account id. |

**Responses**: OK `AccountResponse`: The account.

**Notes**

- An inactive account is returned by id, even though GET /v3/accounts hides inactive accounts.
- An unknown id returns `404`.

---

### `GET /v3/accounts/{id}/balance`: Gets account balance.

Operation `GetAccountBalance` · permission `read:account-balance`

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `id` | route | `int` |  | The account id. |

**Query string**: `GetAccountBalanceQuery`

| field | type | default | validation | description |
|---|---|---|---|---|
| `date` | `DateTime?` |  |  | The balance date. |
| `costCenterId` | `int?` |  | GreaterThan(0) .When(x => x.CostCenterId.HasValue) | The cost-center filter. |
| `customerId` | `int?` |  | GreaterThan(0) .When(x => x.CustomerId.HasValue) | The customer filter. |
| `supplierId` | `int?` |  | GreaterThan(0) .When(x => x.SupplierId.HasValue) | The supplier filter. |
| `isPostedOnly` | `bool` | true |  | Whether only posted transactions are included. |

**Responses**: OK `AccountBalanceResponse`: Account balance.

**Notes**

- `isPostedOnly` defaults to `true`, so omitting it leaves unposted documents out of the balance.
- With `isPostedOnly=false`, unposted documents are counted. Unposted `NR` and `NP` documents are the exception: they count only when an organization setting allows it and the document is not archived, so results can differ between organizations.
- `date` is an inclusive upper limit on the document date. It is compared as sent, with no rounding to the end of the day. Omit it to include all dates.
- The account's opening balance is always included, even when you filter by `costCenterId`, `customerId` or `supplierId`.
- The sign follows the account's normal balance side. Debit accounts return debit minus credit, and all other accounts return credit minus debit.
- Recurring journal entry templates are not counted.
- Only entry lines that carry exactly that `costCenterId`, `customerId` or `supplierId` are counted.
- Line amounts are summed as stored, with no currency filter and no conversion. The total is rounded to 2 decimal places.
- `404` is returned only when the account id does not exist. If no entries match, you still get a balance.

---

### `GET /v3/accounts/nodes`: Lists leaf account nodes.

Operation `GetAccountNodes` · permission `read:account`

**Query string**: `GetAccountNodesQuery`

| field | type | default | validation | description |
|---|---|---|---|---|
| `type` | `AccountType?` |  | NotNull(); Must(value => !value.HasValue \|\| Enum.IsDefined(typeof(AccountType), value.Value)) | The account node type. |

**Responses**: OK `IReadOnlyCollection<AccountNodeResponse>`: Leaf account nodes.

**Notes**

- `type` is required. Omitting it returns `400`.
- Returns the chart of accounts nodes of the given `type` that have no child node of the same type, ordered by node code.
- The result is not paged and not filtered by active status. Every matching node is returned in one response.
- When no node matches you get `404`, not `200` with an empty list.

## Types

### `AccountBalanceResponse`

Response describing an account balance.

| field | type | description |
|---|---|---|
| `account` | `AccountReference` | The account reference. |
| `balance` | `decimal` | The balance. |
| `date` | `DateTime?` | The balance date filter. |
| `costCenter` | `CostCenterReference` | The cost-center reference. |
| `customer` | `CustomerReference` | The customer reference. |
| `supplier` | `SupplierReference` | The supplier reference. |
| `isPostedOnly` | `bool` | Whether only posted transactions were included. |

### `AccountNodeResponse`

Response describing a chart-of-accounts node.

| field | type | description |
|---|---|---|
| `id` | `int` | The node id. |
| `nodeCode` | `string` | The account code. |
| `nodeDescription` | `string` | The account description / name. |
| `alias` | `string` | The short alias used on documents and reports. |
| `nodeType` | `AccountType?` | The account type (Asset, Liability, Equity, Revenue, Expense). |
| `typicalBalance` | `DebitCreditSide?` | The typical balance side of the account (Debit or Credit). |
| `parentNodeId` | `int?` | The id of the parent node in the chart-of-accounts tree. |
| `postingTypeId` | `int?` | The id of the posting type (built-in system classification). |
| `postingTypeUser` | `int?` | The id of the user-defined posting type, when applicable. |
| `acceptCostCenter` | `bool?` | Whether postings to this account must specify a cost center. |
| `incashFlow` | `bool?` | Whether this account is included in cash-flow reporting. |
| `cashFlowParentNodeId` | `int?` | The id of the parent node in the cash-flow tree. |
| `cashFlowTitle` | `string` | The cash-flow display title. |
| `cashFlowSectionId` | `int?` | The id of the cash-flow section the account rolls up to. |
| `budgetVariance` | `BudgetVarianceDirection?` | The direction (favorable / unfavorable) of variance for budgeting. |
| `nodeClassification` | `string` | The custom classification label assigned to the node. |

### `AccountReference`

Lightweight account reference (id + code + name).

| field | type | description |
|---|---|---|
| `id` | `int` | The account id. |
| `code` | `string` | The account code. |
| `name` | `string` | The account name. |

### `AccountResponse`

Response describing an account.

| field | type | description |
|---|---|---|
| `id` | `int` | The account identifier. |
| `accountCode` | `string` | The account code. |
| `description` | `string` | The account description. |
| `classificationCode` | `string` | The classification code. |
| `accountType` | `AccountType?` | The account type. |
| `acceptCostCenter` | `bool` | Whether the account accepts cost centers. |

### `AccountType`

Account types exposed by the v3 API.

Values (sent/returned as the name): `RealizedGainExchange`=0, `RealizedLossExchange`=1, `UnrealizedGainExchange`=2, `UnrealizedLossExchange`=3, `Cash`=4, `AccountsReceivable`=5, `AccountsPayable`=6, `Sales`=7, `ServicesSales`=8, `SalesReturns`=9, `Purchase`=10, `PurchaseReturns`=11, `NotesReceivable`=12, `NotesPayable`=13, `Inventory`=14, `COGS`=15, `SalesDiscount`=16, `OtherRevenue`=17, `Waste`=18, `Bank`=19, `RetainedEarning`=20, `SalesTax`=21, `WithholdingTax`=22, `PurchaseDiscount`=23, `Adjustment`=24, `AddedTax`=25, `EndingInventory`=26, `PurchaseAddedTax`=27

### `BudgetVarianceDirection`

Budget variance direction for chart-of-accounts nodes.

Values (sent/returned as the name): `Positive`=0, `Negative`=1

### `CostCenterReference`

Lightweight cost-center reference (id + code + name).

| field | type | description |
|---|---|---|
| `id` | `int` | The cost-center id. |
| `code` | `string` | The cost-center code. |
| `name` | `string` | The cost-center name. |

### `CustomerReference`

Lightweight customer reference (id + code + name).

| field | type | description |
|---|---|---|
| `id` | `int` | The customer id. |
| `code` | `string` | The customer code. |
| `name` | `string` | The customer name. |

### `DebitCreditSide`

Debit/credit side for accounting lines.

Values (sent/returned as the name): `Debit`=0, `Credit`=1

### `SupplierReference`

Lightweight supplier reference (id + code + name).

| field | type | description |
|---|---|---|
| `id` | `int` | The supplier id. |
| `code` | `string` | The supplier code. |
| `name` | `string` | The supplier name. |