List the demand index · Ownrecord docs

The demand index: per customer-location jurisdiction, the demand across every organization in one mode (spec §42.2, README §7). For each jurisdiction with a signal: waitlist entries by stage (waiting, pending, notified, left) with the waiting entries' estimated value; checkouts paused there in the window (blockedCheckouts, by reason); net sales in the window where the knowledge base is only at coverage L0 (l0Sales, where quotes are out of scope, with an EUR equivalent for sorting); and subscribers' legal entities established there. With each, how many organizations and brands it comes from, never which: the index holds counts and sums only, no customer data. coverage is the jurisdiction's level, target and tier, to compare demand with what the knowledge base supports.

Sort by waitlist, blocked_checkouts, l0_sales, entities or jurisdiction; the window is this calendar month and the ones before it (months, default 12). Platform staff only.

At a glance

REST: GET /api/v1/tax/knowledge/demand
MCP tool: knowledge_demand_list
Operation ID: knowledge.demand.list
Scope: Platform
Permission: tax_knowledge:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the tax_knowledge:read scope
Since: M7

Request

Query parameters

Field	Type	Required	Description
`mode`	one of `live`, `test`	No	Whose demand: live sales and waitlists (default), or test mode's.
`months`	integer (1 to 36)	No	The window for blocked checkouts and L0 sales: this calendar month and the ones before it (1–36, default 12).
`sort`	one of `jurisdiction`, `waitlist`, `blocked_checkouts`, `l0_sales`, `entities`	No	`waitlist` (waiting entries), `blocked_checkouts`, `l0_sales` (EUR equivalent), `entities` or `jurisdiction`.
`order`	one of `asc`, `desc`	No
`jurisdiction`	string	No	Only this jurisdiction's row.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"demand_index"`
`livemode`	boolean
`window`	object	Blocked checkouts and L0 sales are counted from `from` (a month's first day) to `to` (today, UTC).
`window.months`	integer (at least 1)
`window.from`	string
`window.to`	string
`sort`	one of `jurisdiction`, `waitlist`, `blocked_checkouts`, `l0_sales`, `entities`
`order`	one of `asc`, `desc`
`fxRateDate`	string or null	The ECB publication used for `eurEquivalent`.
`knowledgeCommit`	string or null	The loaded knowledge the coverage levels come from.
`data`	array of object
`data[].jurisdiction`	string	The customer-location jurisdiction: `DE`, `US-TX`, a territory's code (`AX`) or an unknown country.
`data[].name`	string or null
`data[].territoryOf`	string or null	For a territory: the jurisdiction whose VAT area it belongs to or borders.
`data[].coverage`	object or null	The knowledge base's coverage; null when it has no jurisdiction record for the place.
`data[].waitlist`	object
`data[].waitlist.waiting`	integer (at least 0)	Confirmed entries waiting for the brand to be able to sell.
`data[].waitlist.pending`	integer (at least 0)	Entries whose email isn't confirmed yet.
`data[].waitlist.notified`	integer (at least 0)	Entries told once that the brand can sell (the jurisdiction opened).
`data[].waitlist.left`	integer (at least 0)	Entries whose customer left the waitlist.
`data[].waitlist.organizations`	integer (at least 0)
`data[].waitlist.brands`	integer (at least 0)
`data[].waitlist.estimatedValue`	array of money	What the waiting entries wanted to buy, per currency.
`data[].blockedCheckouts`	object
`data[].blockedCheckouts.total`	integer (at least 0)	Checkouts paused for a customer there in the window (once per session and reason).
`data[].blockedCheckouts.registrationRequired`	integer (at least 0)
`data[].blockedCheckouts.jurisdictionBlocked`	integer (at least 0)
`data[].blockedCheckouts.other`	integer (at least 0)	Other reasons, e.g. unclear location evidence.
`data[].blockedCheckouts.organizations`	integer (at least 0)
`data[].blockedCheckouts.brands`	integer (at least 0)
`data[].l0Sales`	object or null	Only for jurisdictions at coverage L0, where quotes are out of scope.
`data[].establishedEntities`	object
`data[].establishedEntities.entities`	integer (at least 0)	Subscribers' legal entities established there (not archived).
`data[].establishedEntities.organizations`	integer (at least 0)

Examples

Live demand over 12 months

HTTP

GET /api/v1/tax/knowledge/demand
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "demand_index",
  "livemode": true,
  "window": {
    "months": 12,
    "from": "2025-11-01",
    "to": "2026-10-19"
  },
  "sort": "waitlist",
  "order": "desc",
  "fxRateDate": "2026-10-16",
  "knowledgeCommit": "3c6925993d7a270b392e44860572530707616da4",
  "data": [
    {
      "jurisdiction": "GB",
      "name": "United Kingdom",
      "territoryOf": null,
      "coverage": {
        "level": "L2",
        "target": "L3",
        "tier": 1
      },
      "waitlist": {
        "waiting": 42,
        "pending": 6,
        "notified": 0,
        "left": 2,
        "organizations": 5,
        "brands": 7,
        "estimatedValue": [
          {
            "amount": "3150000000",
            "currency": "EUR"
          }
        ]
      },
      "blockedCheckouts": {
        "total": 118,
        "registrationRequired": 112,
        "jurisdictionBlocked": 0,
        "other": 6,
        "organizations": 6,
        "brands": 9
      },
      "l0Sales": null,
      "establishedEntities": {
        "entities": 3,
        "organizations": 3
      }
    },
    {
      "jurisdiction": "KE",
      "name": "Kenya",
      "territoryOf": null,
      "coverage": {
        "level": "L0",
        "target": "L1",
        "tier": 3
      },
      "waitlist": {
        "waiting": 0,
        "pending": 0,
        "notified": 0,
        "left": 0,
        "organizations": 0,
        "brands": 0,
        "estimatedValue": []
      },
      "blockedCheckouts": {
        "total": 0,
        "registrationRequired": 0,
        "jurisdictionBlocked": 0,
        "other": 0,
        "organizations": 0,
        "brands": 0
      },
      "l0Sales": {
        "invoices": 214,
        "net": [
          {
            "amount": "18400000000",
            "currency": "EUR"
          },
          {
            "amount": "2500000000",
            "currency": "USD"
          }
        ],
        "organizations": 4,
        "eurEquivalent": {
          "amount": "20550000000",
          "currency": "EUR"
        }
      },
      "establishedEntities": {
        "entities": 0,
        "organizations": 0
      }
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter, the sort or the window is invalid.	Fix the fields listed in `details.issues` and send the request again.
`permission_denied`	403	You aren't platform staff (the index aggregates every organization's demand).	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.

At a glance#

Request#

Query parameters#

Response#

Examples#

Live demand over 12 months#

Errors#