Search Tax Configuration

POST /accounting/tax-configurations/search

Group: Accounting › Tax Configurations · Operation ID: searchTaxConfiguration

Returns the tax configurations that match the given filters. Each match is the full record, with its tax codes and GL account mappings.

Open in the interactive reference

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: 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'. 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.

Example:

{
  "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 of 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'.
items[].externalId string no An external system's identifier for this configuration, set when it was migrated from another system.
items[].lastModifiedDate string (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 of 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 string (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[].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 of object yes The GL accounts this tax code books to, one per 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.
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.

Statuses