# List the entity's demand by jurisdiction > The waitlist.demand.list operation: GET /api/v1/waitlist/demand in the REST API and the waitlist_demand_list tool in the MCP server. Where the legal entity's brands can't sell to consumers yet, and what it would take: one row per customer-location jurisdiction with waitlist entries or blocked checkouts, all brands combined, in the mode of the request (spec §23). Each row has the waitlist by stage (`waiting`, `pending`, `notified`, `left`) and the waiting entries' `estimatedMonthlyValue` per currency (recurring prices per month; one-time prices and credit packs counted once, as a first month's purchase); the checkouts paused there in the window (`blockedCheckouts`, by reason); and the regimes that apply there: the entity's registration state, the prerequisites with their lead times and status, `leadTimeDays` (the longest lead time of what isn't done) and the compliance effort (a fiscal representative, a local agent, the filing frequency). `brands` splits the counts per brand; they add up to the row. Counts and sums only: no customer is named. Sort by `waitlist`, `monthly_value` (EUR equivalent), `blocked_checkouts`, `lead_time` or `jurisdiction`; `brand` limits every count to one brand of the entity. Callers who can't read registrations get the knowledge base's side only (`registrationsVisible: false`). ## At a glance - **REST:** `GET /api/v1/waitlist/demand` - **MCP tool:** `waitlist_demand_list` - **Operation ID:** `waitlist.demand.list` - **Scope:** Legal entity - **Permission:** `waitlist:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Authentication:** API key with the `waitlist:read` scope - **Since:** M7 ## Request ### Query parameters | Field | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `months` | integer (1 to 36) | No | The window for blocked checkouts: this calendar month and the ones before it (1–36, default 12). | | `sort` | one of `jurisdiction`, `waitlist`, `monthly_value`, `blocked_checkouts`, `lead_time` | No | `waitlist` (waiting entries), `monthly_value` (EUR equivalent), `blocked_checkouts`, `lead_time` or `jurisdiction`. | | `order` | one of `asc`, `desc` | No | | | `brand` | `brd_…` ID | No | Only this brand of the entity (`brd_…`); all brands when absent. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `object` | `"entity_demand"` | | | `entityId` | `ent_…` ID | | | `livemode` | boolean | | | `window` | object | | | `window.months` | integer (at least 1) | | | `window.from` | string | | | `window.to` | string | | | `sort` | one of `jurisdiction`, `waitlist`, `monthly_value`, `blocked_checkouts`, `lead_time` | | | `order` | one of `asc`, `desc` | | | `brand` | `brd_…` ID or null | The brand filter, or null for every brand. | | `brands` | array of object | The entity's brands (the split's names and the filter's choices). | | `brands[].id` | `brd_…` ID | | | `brands[].name` | string | | | `brands[].slug` | string | | | `registrationsVisible` | boolean | False when you can't read registrations: `registration` and prerequisite statuses are null. | | `fxRateDate` | string or null | | | `data` | array of object | | | `data[].jurisdiction` | string | The customer-location jurisdiction: `GB`, `US-TX`, a territory's code. | | `data[].name` | string or null | | | `data[].territoryOf` | string or null | | | `data[].waitlist` | object | | | `data[].waitlist.waiting` | integer (at least 0) | Confirmed entries waiting for the brand to be able to sell there. | | `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 there. | | `data[].waitlist.left` | integer (at least 0) | Entries whose customer left the waitlist. | | `data[].waitlist.estimatedMonthlyValue` | object | What the waiting entries wanted to buy, per month and currency. | | `data[].waitlist.estimatedMonthlyValue.total` | array of money | | | `data[].waitlist.estimatedMonthlyValue.recurring` | array of money | Recurring prices, per month. | | `data[].waitlist.estimatedMonthlyValue.oneTime` | array of money | One-time prices and credit packs, counted once (as a first month's purchase). | | `data[].blockedCheckouts` | object | | | `data[].blockedCheckouts.total` | integer (at least 0) | Checkouts paused 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[].monthlyValueEur` | money or null | The estimated monthly value in EUR at the ECB rates of `fxRateDate` (for sorting). | | `data[].leadTimeDays` | integer or null | The longest lead time of the row's regimes. | | `data[].regimes` | array of object | The regimes that apply there and the registration. | | `data[].regimes[].regimeId` | string | | | `data[].regimes[].name` | string or null | | | `data[].regimes[].registration` | object or null | The entity's registration; null when it has none, or you can't read registrations. | | `data[].regimes[].prerequisites` | array of object | | | `data[].regimes[].prerequisites[].code` | string | | | `data[].regimes[].prerequisites[].description` | string or null | | | `data[].regimes[].prerequisites[].leadTimeDays` | integer or null | | | `data[].regimes[].prerequisites[].status` | one of `todo`, `in_progress`, `done` or null | | | `data[].regimes[].leadTimeDays` | integer or null | The longest lead time of the prerequisites not done yet (0 when all are done). | | `data[].regimes[].typicalProcessingDays` | integer or null | | | `data[].regimes[].effort` | object | | | `data[].regimes[].effort.fiscalRepresentative` | boolean or null | | | `data[].regimes[].effort.localAgent` | boolean or null | | | `data[].regimes[].effort.filingFrequency` | one of `monthly`, `quarterly`, `annual`, `varies` or null | | | `data[].brands` | array of object | The same counts per brand with a signal there; they add up to the row. | | `data[].brands[].brandId` | `brd_…` ID | | | `data[].brands[].waitlist` | object | | | `data[].brands[].waitlist.waiting` | integer (at least 0) | Confirmed entries waiting for the brand to be able to sell there. | | `data[].brands[].waitlist.pending` | integer (at least 0) | Entries whose email isn't confirmed yet. | | `data[].brands[].waitlist.notified` | integer (at least 0) | Entries told once that the brand can sell there. | | `data[].brands[].waitlist.left` | integer (at least 0) | Entries whose customer left the waitlist. | | `data[].brands[].waitlist.estimatedMonthlyValue` | object | What the waiting entries wanted to buy, per month and currency. | | `data[].brands[].blockedCheckouts` | object | | | `data[].brands[].blockedCheckouts.total` | integer (at least 0) | Checkouts paused there in the window (once per session and reason). | | `data[].brands[].blockedCheckouts.registrationRequired` | integer (at least 0) | | | `data[].brands[].blockedCheckouts.jurisdictionBlocked` | integer (at least 0) | | | `data[].brands[].blockedCheckouts.other` | integer (at least 0) | Other reasons, e.g. unclear location evidence. | ## Examples ### Live demand over 12 months ```http GET /api/v1/waitlist/demand Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "entity_demand", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "window": { "months": 12, "from": "2025-11-01", "to": "2026-10-20" }, "sort": "waitlist", "order": "desc", "brand": null, "brands": [ { "id": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "name": "Genno", "slug": "genno" }, { "id": "brd_01m4tx5nj8emwbyf7y9vcf47x5", "name": "Genno Pro", "slug": "genno-pro" } ], "registrationsVisible": true, "fxRateDate": "2026-10-16", "data": [ { "jurisdiction": "GB", "name": "United Kingdom", "territoryOf": null, "waitlist": { "waiting": 12, "pending": 2, "notified": 0, "left": 0, "estimatedMonthlyValue": { "total": [ { "amount": "485000000", "currency": "EUR" } ], "recurring": [ { "amount": "365000000", "currency": "EUR" } ], "oneTime": [ { "amount": "120000000", "currency": "EUR" } ] } }, "blockedCheckouts": { "total": 37, "registrationRequired": 37, "jurisdictionBlocked": 0, "other": 0 }, "monthlyValueEur": { "amount": "485000000", "currency": "EUR" }, "leadTimeDays": 21, "regimes": [ { "regimeId": "GB_VAT_NETP", "name": "UK VAT for non-established sellers", "registration": { "state": "blocked_b2c", "armed": false, "stateReason": "zero_threshold" }, "prerequisites": [ { "code": "gateway_account", "description": "Open a Government Gateway account", "leadTimeDays": 10, "status": "done" }, { "code": "uk_agent", "description": "Appoint a UK tax agent", "leadTimeDays": 21, "status": "todo" } ], "leadTimeDays": 21, "typicalProcessingDays": 30, "effort": { "fiscalRepresentative": false, "localAgent": false, "filingFrequency": "quarterly" } } ], "brands": [ { "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "waitlist": { "waiting": 9, "pending": 1, "notified": 0, "left": 0, "estimatedMonthlyValue": { "total": [ { "amount": "410000000", "currency": "EUR" } ], "recurring": [ { "amount": "290000000", "currency": "EUR" } ], "oneTime": [ { "amount": "120000000", "currency": "EUR" } ] } }, "blockedCheckouts": { "total": 31, "registrationRequired": 31, "jurisdictionBlocked": 0, "other": 0 } }, { "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x5", "waitlist": { "waiting": 3, "pending": 1, "notified": 0, "left": 0, "estimatedMonthlyValue": { "total": [ { "amount": "75000000", "currency": "EUR" } ], "recurring": [ { "amount": "75000000", "currency": "EUR" } ], "oneTime": [] } }, "blockedCheckouts": { "total": 6, "registrationRequired": 6, "jurisdictionBlocked": 0, "other": 0 } } ] } ] } ``` ## Errors | Code | HTTP status | When | What to do | | ---------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | The window, the sort or the brand is malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no legal entity (an org key without `Ownrecord-Entity`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | The `brand` filter isn't a brand of this entity. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't read this entity's waitlist (brand-scoped members never can: the page combines brands). | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).