# Search Account

`POST /accounting/accounts/search`

Group: Accounting › Accounts · Operation ID: `searchAccount`

Returns the accounts that match the given filters, ordered by account number.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchAccount)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchAccountInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. An account must match every filter you send. Omit to return all accounts. |
| `filters.id` | string | no | Limits results to the account with this identifier. The match is exact. |
| `filters.accountNumber` | string | no | Limits results to the account with this number. Pair it with chartOfAccountsId, since the number is unique only within a chart of accounts. |
| `filters.accountName` | string | no | Limits results to accounts whose name contains this text. The match is case-insensitive. |
| `filters.chartOfAccountsId` | string | no | Limits results to accounts in this chart of accounts, by its identifier. An identifier that matches none returns an empty page. |
| `filters.accountType` | string | no | Limits results to accounts of this type. Possible values: 'asset', 'liability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense'. Any other value matches nothing. |
| `filters.accountSubType` | string | no | Limits results to accounts of this sub-type. Possible values: 'bank', 'accountsReceivable', 'fixedAsset', 'cip', 'prepaidExpenses', 'deferredExpenses', 'otherCurrentAsset', 'otherAsset', 'unbilledReceivable', 'longTermAsset', 'accountsPayable', 'creditCard', 'deferredRevenue', 'otherCurrentLiability', 'longTermLiability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense', 'otherComprehensiveIncome'. Any other value matches nothing. |
| `filters.accountStatus` | string | no | Limits results to accounts with this status. Possible values: 'enabled', 'disabled', 'draft', 'draftErrors'. Any other value matches nothing. |
| `filters.entityId` | string | no | Limits results to accounts denominated for this legal entity, by its identifier. Only bank and credit-card accounts name an entity, so no other sub-type matches. An identifier that matches none returns an empty page. |
| `filters.groupingAccount` | boolean | no | True returns only grouping accounts, false only posting accounts. Omit for both. |
| `filters.externalIdentifier` | object | no | Limits results to accounts carrying this external identifier. Both fieldName and value are required. Several accounts may share a value, so this returns the items array, not a single record. |
| `filters.externalIdentifier.fieldName` | string | yes | The configured key of the external identifier, a camelCase slug such as 'netsuiteAccountId'. It must be the fieldName of an existing configuration, or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER. |
| `filters.externalIdentifier.value` | string | yes | The identifier as the source system holds it. The match is exact and case-sensitive. |
| `page` | object | no | Pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `page.size` | number | no | The number of accounts per page, between 1 and 200. Defaults to 50. A value outside that range fails with INVALID_PAGE_SIZE rather than being adjusted. |

Example:

```json
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accountNumber": "<accountNumber>",
    "accountName": "<accountName>",
    "chartOfAccountsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accountType": "<accountType>",
    "accountSubType": "<accountSubType>",
    "accountStatus": "<accountStatus>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "groupingAccount": true,
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchAccountOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The accounts that match, ordered by account number. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the account. |
| `items[].accountNumber` | string | yes | The account number, unique within its chart of accounts. |
| `items[].accountName` | string | yes | The display name of the account. |
| `items[].accountType` | string | yes | The top-level classification of the account. Possible values: 'asset', 'liability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense'. |
| `items[].accountSubType` | string | no | A finer classification within accountType. Possible values: 'bank', 'accountsReceivable', 'fixedAsset', 'cip', 'prepaidExpenses', 'deferredExpenses', 'otherCurrentAsset', 'otherAsset', 'unbilledReceivable', 'longTermAsset', 'accountsPayable', 'creditCard', 'deferredRevenue', 'otherCurrentLiability', 'longTermLiability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense', 'otherComprehensiveIncome'. Absent when none is assigned. |
| `items[].accountStatus` | string | no | The lifecycle status of the account. Possible values: 'enabled' (available on transactions), 'disabled' (not available for new transactions), 'draft' (created but not yet reviewed), 'draftErrors' (a draft with validation errors to resolve before it can be enabled). |
| `items[].description` | string | no | A free-form description of the account. Absent when none was set. |
| `items[].chartOfAccountsId` | string | yes | The identifier of the chart of accounts this account belongs to. An account belongs to exactly one. See id on GET accounting/chart-of-accounts/:id. |
| `items[].parentAccountId` | string | no | The identifier of the parent account this account rolls up to. Absent for a top-level account. See id on GET accounting/accounts/:id. |
| `items[].groupingAccount` | boolean | yes | Whether this is a grouping (rollup) account. Balances from child accounts aggregate here, and journal entries cannot be posted to it directly. |
| `items[].entityId` | string | no | The identifier of the legal entity this account is denominated for. Set only on bank and credit-card accounts. See id on GET base/entities. |
| `items[].currency` | string | no | The account's currency. Format ISO 4217, for example 'USD'. Set only on accounts linked to a cash account, alongside entityId. |
| `items[].revaluation` | boolean | no | Whether balances on this account are revalued for exchange-rate changes. |
| `items[].payOnBehalf` | boolean | no | Whether this account takes part in pay-on-behalf accounting. |
| `items[].elimination` | boolean | no | Whether this account is eliminated during consolidation. |
| `items[].exchangeRateType` | string | no | Which rate translates this account's amounts on revaluation. Possible values: 'historical', 'average', 'current'. Absent on grouping accounts. |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the account record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].externalIdentifiers` | array of object | no | External identifiers owned by other systems, at most one per fieldName. An empty array when the account has none. |
| `items[].externalIdentifiers[].fieldName` | string | yes | The configured key of the external identifier, a camelCase slug such as 'netsuiteAccountId'. It is the fieldName of an existing account external-identifier configuration. |
| `items[].externalIdentifiers[].value` | string | yes | The identifier as the source system holds it. |
| `items[].externalIdentifiers[].externalUrl` | string | no | An absolute http(s) link to the object in the source system. Absent when none is stored. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page. |

## Errors

| Code | Status |
| --- | --- |
| `UNKNOWN_EXTERNAL_IDENTIFIER` | 400 |
| `INVALID_PAGE_SIZE` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: UNKNOWN_EXTERNAL_IDENTIFIER, INVALID_PAGE_SIZE
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error