Skip to main content
POST
/
tax
/
business_entities
/
{business_entity_id}
/
rates
/
lookup
Resolve the applicable tax rate for a destination
curl --request POST \
  --url https://api.zenskar.com/tax/business_entities/{business_entity_id}/rates/lookup \
  --header 'Content-Type: application/json' \
  --header 'organisation: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tax_category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "country_code": "<string>",
  "effective_date": "2023-12-25",
  "state_code": "<string>",
  "city": "<string>",
  "zip_code": "<string>"
}
'
{
  "source_jurisdiction_rate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rate_breakdown": [
    {
      "tax_name": "<string>",
      "rate_percent": "<string>",
      "is_compound": true,
      "compound_order": 123,
      "source_tax_rate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "jurisdiction_level": "<string>",
      "jurisdiction_code": "<string>"
    }
  ],
  "fingerprint": "<string>"
}

Authorizations

​
x-api-key
string
header
default:<your-api-key>
required
​
organisation
string
header
default:<your-organisation-id>
required

Path Parameters

​
business_entity_id
string<uuid>
required

Body

application/json

Request body for the rate-lookup endpoint.

Strict-level matching against the deepest field provided. A missing input field is treated as 'row must be empty at that level' — not 'ignore that level'. So city=SF alone matches rows with state='' AND city='SF' AND zip=''. Whatever combination of geography fields the caller supplies, the lookup either matches a row pinned to that exact shape or returns [].

​
tax_category_id
string<uuid>
required
​
country_code
string
required
Required string length: 2
​
effective_date
string<date>
required
​
state_code
string | null
Maximum string length: 10
​
city
string | null
Maximum string length: 100
​
zip_code
string | null
Maximum string length: 20

Response

Successful Response

Output of :meth:TaxLookupService.resolve_rates_for_destination — one matched jurisdiction.

source_jurisdiction_rate_id is provenance (which tax_jurisdiction_rates row matched). fingerprint is a sha256 over the resolved set so a future reverify can detect drift against current rate tables without re-shipping the breakdown.

​
source_jurisdiction_rate_id
string<uuid>
required
​
rate_breakdown
RateRow · object[]
required
​
fingerprint
string
required