Skip to content
Docs
APISign inStart free

List tax jurisdictions and their coverage

The knowledge.jurisdictions.list operation: GET /api/v1/tax/knowledge/jurisdictions in the REST API and the knowledge_jurisdictions_list tool in the MCP server.

GET/api/v1/tax/knowledge/jurisdictions

Lists the jurisdictions of the Jurisdiction Knowledge Base: the coverage map. Each one has its coverage level (L0 known, L1 tax, L2 registration, L3 filing, L4 connector) and target, its priority tier (1 = launch), the status of its own record (meta), and counts of its records by status (records), with their open questions and the earliest nextReviewBy.

Filter by tier, coverage level or the jurisdiction record's status. Sorted by ID; paginate with limit (1–100, default 100) and starting_after (the previous next_cursor). Records at researched or cross_checked aren't reviewed yet: live mode uses only reviewed or verified records (spec §7.2).

At a glance

  • REST: GET /api/v1/tax/knowledge/jurisdictions
  • MCP tool: knowledge_jurisdictions_list
  • Operation ID: knowledge.jurisdictions.list
  • Scope: Platform
  • Permission: tax_knowledge:read
  • Risk tier: read
  • Dry run: Not supported
  • Idempotency: Not needed (read only)
  • Modes: Test and live
  • Pagination: limit (at most 100) and starting_after
  • Authentication: API key with the tax_knowledge:read scope
  • Since: M3

Request

Query parameters

FieldTypeRequiredDescription
tierintegerNo
levelone of L0, L1, L2, L3, L4No
statusone of researched, cross_checked, reviewed, verified, retiredNo
limitinteger (1 to 100)No
starting_afterstringNo

Response

200 OK with a JSON object, a page of the list (newest first):

FieldTypeDescription
object"list"
dataarray of object
data[].idstring
data[].object"tax_jurisdiction"
data[].namestring
data[].typeone of country, subdivision, union
data[].parentstring
data[].euMemberboolean
data[].currencystring
data[].timezonestring
data[].coverageobject
data[].coverage.levelone of L0, L1, L2, L3, L4
data[].coverage.targetone of L0, L1, L2, L3, L4
data[].coverage.tier1 or 2 or 3
data[].authorityobject
data[].authority.namestring
data[].authority.urlstring
data[].authority.portalUrlstring
data[].taxIdobject
data[].taxId.typestring
data[].taxId.formatstring
data[].taxId.examplestring
data[].taxId.validationobject
data[].taxId.validation.serviceone of VIES, HMRC, CH_UID, ABN_LOOKUP, none, other
data[].taxId.validation.urlstring
data[].metaobject
data[].meta.statusone of researched, cross_checked, reviewed, verified, retired
data[].meta.fixtureboolean
data[].meta.confidenceone of high, medium, low
data[].meta.sourceIdsarray of string
data[].meta.openQuestionsinteger (at least 0)
data[].meta.unsupportedRulesinteger (at least 0)
data[].meta.blockingUnsupportedRulesinteger (at least 0)
data[].meta.reviewedBystring
data[].meta.reviewedAtstring
data[].meta.verifiedBystring
data[].meta.verifiedAtstring
data[].meta.nextReviewBystring
data[].meta.knowledgeRefobject
data[].meta.knowledgeRef.pathstring
data[].meta.knowledgeRef.commitstring
data[].recordsobject
data[].records.totalinteger (at least 0)
data[].records.researchedinteger (at least 0)
data[].records.cross_checkedinteger (at least 0)
data[].records.reviewedinteger (at least 0)
data[].records.verifiedinteger (at least 0)
data[].records.retiredinteger (at least 0)
data[].openQuestionsinteger (at least 0)
data[].unsupportedRulesinteger (at least 0)
data[].nextReviewBystring
has_moreboolean
next_cursorstring or null

Examples

Tier 1 jurisdictions

HTTP
GET /api/v1/tax/knowledge/jurisdictions?tier=1
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "HR",
      "object": "tax_jurisdiction",
      "name": "Croatia",
      "type": "country",
      "euMember": true,
      "currency": "EUR",
      "timezone": "Europe/Zagreb",
      "coverage": {
        "level": "L3",
        "target": "L3",
        "tier": 1
      },
      "authority": {
        "name": "Porezna uprava",
        "url": "https://www.porezna-uprava.hr"
      },
      "taxId": {
        "type": "eu_vat",
        "format": "^HR\\d{11}$",
        "validation": {
          "service": "VIES"
        }
      },
      "meta": {
        "status": "reviewed",
        "fixture": false,
        "confidence": "high",
        "sourceIds": ["HR:S1", "HR:S4"],
        "openQuestions": 0,
        "unsupportedRules": 0,
        "blockingUnsupportedRules": 0,
        "reviewedBy": "Ana Horvat",
        "reviewedAt": "2026-10-10",
        "nextReviewBy": "2027-04-13",
        "knowledgeRef": {
          "path": "data/tax/knowledge/jurisdictions/HR/jurisdiction.yaml",
          "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1"
        }
      },
      "records": {
        "total": 14,
        "researched": 2,
        "cross_checked": 4,
        "reviewed": 8,
        "verified": 0,
        "retired": 0
      },
      "openQuestions": 3,
      "unsupportedRules": 1,
      "nextReviewBy": "2027-04-13"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

CodeHTTP statusWhenWhat to do
validation_failed400A filter isn't a tier (1–3), a coverage level or a record status, or the page size is invalid.Fix the fields listed in details.issues and send the request again.
permission_denied403Your credentials can't read tax knowledge.Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.