# Search tax configurations

Operation ID: `searchTaxConfiguration`

Group: Accounting › Tax Configurations

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchTaxConfiguration)

`POST /accounting/tax-configurations/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches tax configurations. Each tax configuration in the response includes its tax codes and the general ledger accounts of each tax code.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · 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`: searchTaxConfigurationInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. A tax configuration must match every filter you send. Omit to return all tax configurations. |
| `filters.id` | string | no | Limits results to the tax configuration with this identifier. |
| `filters.entityId` | string | no | Limits results to the configuration of this legal entity. An entity has at most one, so this returns at most one match. See id on GET base/entities. |
| `filters.status` | string | no | Limits results to configurations of this status. Possible values: 'Active', 'Inactive'. Any other value matches no configuration. |
| `filters.taxRegime` | string | no | Limits results to configurations of this tax regime. Possible values: 'EU_VAT', 'India_GST', 'Canada_GST', 'Ghana_VAT', 'SingleRate_GST', 'Mexico_IVA'. Any other value matches no configuration. |
| `page` | object | no | The pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of tax configurations per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "<status>",
    "taxRegime": "<taxRegime>"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchTaxConfigurationOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The matching tax configurations for this page, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the tax configuration. |
| `items[].entityId` | string | yes | The legal entity this configuration belongs to. An entity has at most one tax configuration. See id on GET base/entities. |
| `items[].entityName` | string | no | The name of the owning legal entity. |
| `items[].status` | string | yes | The status of the tax configuration. The tax codes of an inactive configuration are not offered on documents. Possible values: 'Active', 'Inactive'. |
| `items[].taxRegime` | string | yes | The tax system that determines which tax components are valid. Possible values: 'EU_VAT', 'India_GST', 'Canada_GST', 'Ghana_VAT', 'SingleRate_GST', 'Mexico_IVA'. |
| `items[].externalId` | string | no | An external system's identifier for this configuration, set when it was migrated from another system. |
| `items[].lastModifiedDate` | date-time | yes | The date and time the tax configuration record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array<object> | yes | The tax codes of this configuration, in display order. Every configuration has at least one. |
| `items[].lines[].id` | string | yes | The unique identifier for the tax code line. |
| `items[].lines[].taxCode` | string | no | The business tax code as printed on source documents, for example 'V19EUG' or 'U00EU'. Absent when none was supplied. |
| `items[].lines[].title` | string | yes | The display title of the tax code. Unique within the configuration. |
| `items[].lines[].comment` | string | no | A free-form note on when to use this tax code. Absent when none was set. |
| `items[].lines[].vatDeclarationField` | string | no | The box or boxes on the VAT return that this code feeds, taken verbatim from the tax authority form, for example '66' or '46+47+67'. Free text, not evaluated. Absent when none was set. |
| `items[].lines[].percentage` | decimal | yes | The tax rate, as a decimal fraction. For example, 0.19 is 19%. 0 for a zero-rated or exempt code. |
| `items[].lines[].rateType` | string | yes | The legal rate classification of the tax code. Possible values: 'Standard', 'Reduced', 'SuperReduced', 'Zero', 'Exempt'. |
| `items[].lines[].scope` | string | yes | The territorial scope of the transaction. Possible values: 'Domestic', 'IntraEU_B2B', 'IntraEU_B2C', 'ExtraEU_Goods', 'ExtraEU_Services'. |
| `items[].lines[].direction` | string | yes | Which side the tax sits on. 'Input' is tax paid on purchases, 'Output' is tax charged on sales. Possible values: 'Input', 'Output'. |
| `items[].lines[].isReverseCharge` | boolean | yes | Whether the recipient rather than the supplier accounts for the tax, for example under §13b UStG. A reverse-charge line books a second, crediting entry to reverseChargeCreditAccountId on each of its accounts. |
| `items[].lines[].cashBasis` | boolean | yes | Cash basis: the tax becomes creditable only when the bill is paid. It posts to the uncollected account and moves to the collected account on payment. |
| `items[].lines[].isActive` | boolean | yes | Whether the tax code is offered for selection on new documents. Inactive codes stay readable on existing documents. |
| `items[].lines[].index` | number | yes | The position of the line within its configuration, used for display order. |
| `items[].lines[].accounts` | array<object> | yes | The general ledger accounts this tax code books to, usually one for each chart of accounts the entity books in. Every tax code has at least one, including exempt and zero-rated codes, which book a tax line at zero. |
| `items[].lines[].accounts[].id` | string | yes | The unique identifier for the account mapping. |
| `items[].lines[].accounts[].chartOfAccountsId` | string | yes | The chart of accounts this mapping applies to. See id on GET accounting/chart-of-accounts/:id. |
| `items[].lines[].accounts[].accountId` | string | yes | The account the tax amount is booked to. See id on GET accounting/accounts/:id. |
| `items[].lines[].accounts[].reverseChargeCreditAccountId` | string | no | The account credited with the offsetting tax amount on a reverse-charge line. Absent when isReverseCharge is false. See id on GET accounting/accounts/:id. |
| `items[].lines[].components` | array<object> | yes | The tax components of this code, with their GL accounts. Empty for a code that has line-level accounts only. |
| `items[].lines[].components[].id` | string | yes | The unique identifier for the component. |
| `items[].lines[].components[].taxComponentCode` | string | yes |  |
| `items[].lines[].components[].percentage` | decimal | yes |  |
| `items[].lines[].components[].isRecoverable` | boolean | yes |  |
| `items[].lines[].components[].accounts` | array<object> | yes |  |
| `items[].lines[].components[].accounts[].id` | string | yes |  |
| `items[].lines[].components[].accounts[].chartOfAccountsId` | string | yes |  |
| `items[].lines[].components[].accounts[].accountId` | string | yes |  |
| `items[].lines[].components[].accounts[].reverseChargeCreditAccountId` | string | no |  |
| `items[].lines[].components[].accounts[].collectedAccountId` | string | no |  |
| `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. |

```json
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "entityName": "<entityName>",
        "status": "<status>",
        "taxRegime": "<taxRegime>",
        "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "lines": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "taxCode": "<taxCode>",
            "title": "<title>",
            "comment": "<comment>",
            "vatDeclarationField": "<vatDeclarationField>",
            "percentage": "19.99",
            "rateType": "<rateType>",
            "scope": "<scope>",
            "direction": "<direction>",
            "isReverseCharge": true,
            "cashBasis": true,
            "isActive": true,
            "index": 0,
            "accounts": [
              null
            ],
            "components": [
              null
            ]
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error