# List registrations > The registrations.list operation: GET /api/v1/registrations in the REST API and the registrations_list tool in the MCP server. Lists the legal entity's registrations in the mode of the request, newest first: one per tax regime of the tax knowledge (spec §10.8), created with the entity in both modes (test mode starts as a copy of live mode), each in its state (`registered`, `grace`, `pre_registration`, `monitored`, `blocked_b2c`, …) with its deadlines and threshold position. Filter by `state`. Each registration has its `state` and `stateReason`, the grace `deadlineAt` and `autoBlockAt` (when new consumer sales stop automatically unless the application is submitted), the prerequisites progress, and the `threshold` position: what the entity sold toward the regime's threshold, all brands combined, with `percent` of the threshold reached. States: `registered`, `grace`, `monitored`, `pre_registration`, `blocked_b2c` (`armed: true` when the first consumer sale will start the grace period), `not_applicable` and `deregistered`. Filter by `state`. Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/registrations` - **MCP tool:** `registrations_list` - **Operation ID:** `registrations.list` - **Scope:** Legal entity - **Permission:** `registrations: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 `registrations:read` scope - **Since:** M3 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------- | | `state` | one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` or array of one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` | No | Only registrations in this state (or these states). | | `limit` | integer (1 to 100) | No | Page size, 1 to 100 (default 10). | | `starting_after` | `regn_…` ID | No | The `next_cursor` of the previous page. | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `regn_…` ID | | | `data[].object` | `"registration"` | | | `data[].entityId` | `ent_…` ID | | | `data[].livemode` | boolean | | | `data[].regimeId` | string | | | `data[].regimeName` | string or null | | | `data[].jurisdictionIds` | array of string | | | `data[].state` | one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` | | | `data[].stateReason` | one of 18 values, e.g. `home_country`, `below_threshold`, `zero_threshold` (all in the OpenAPI document) | | | `data[].stateChangedAt` | date-time | | | `data[].armed` | boolean | | | `data[].triggeredAt` | date-time or null | | | `data[].deadlineAt` | date-time or null | | | `data[].autoBlockAt` | date-time or null | | | `data[].applicationSubmittedAt` | date-time or null | | | `data[].escalationLevel` | integer (0 to 3) | | | `data[].registrationNumber` | string or null | | | `data[].effectiveFrom` | date-time or null | | | `data[].registeredAt` | date-time or null | | | `data[].prerequisitesDone` | boolean | | | `data[].prerequisitesProgress` | object | | | `data[].prerequisitesProgress.done` | integer | | | `data[].prerequisitesProgress.total` | integer | | | `data[].threshold` | object or null | | | `data[].timeZones` | array of string | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `regn_…` ID or null | | ## Examples ### Registrations near or over a threshold ```http GET /api/v1/registrations?state=pre_registration&state=grace&limit=10 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "object": "registration", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "regimeName": "EU One-Stop Shop, Union scheme", "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"], "state": "pre_registration", "stateReason": "pre_registration_ratio_reached", "stateChangedAt": "2026-10-13T12:00:00.000Z", "armed": false, "triggeredAt": null, "deadlineAt": null, "autoBlockAt": null, "applicationSubmittedAt": null, "escalationLevel": 0, "registrationNumber": null, "effectiveFrom": null, "registeredAt": null, "prerequisitesDone": true, "prerequisitesProgress": { "done": 1, "total": 1 }, "threshold": { "status": "below", "window": "calendar_year_current_or_previous", "measure": "eu_cross_border_b2c", "currentWindow": "2026", "previousWindow": "2025", "threshold": { "amount": "10000000000", "currency": "EUR" }, "current": { "amount": "8500000000", "currency": "EUR" }, "previous": { "amount": "0", "currency": "EUR" }, "transactionThreshold": null, "currentTransactions": null, "previousTransactions": null, "worldwideTurnoverDeclared": null, "ratioPpm": "850000", "percent": 85, "detail": "8500.00 EUR counted (earlier window 0.00) against 10000.00 EUR" }, "timeZones": ["Europe/Zagreb"], "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ### Every registration, first page ```http GET /api/v1/registrations?limit=2 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "object": "registration", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "regimeName": "EU One-Stop Shop, Union scheme", "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"], "state": "pre_registration", "stateReason": "pre_registration_ratio_reached", "stateChangedAt": "2026-10-13T12:00:00.000Z", "armed": false, "triggeredAt": null, "deadlineAt": null, "autoBlockAt": null, "applicationSubmittedAt": null, "escalationLevel": 0, "registrationNumber": null, "effectiveFrom": null, "registeredAt": null, "prerequisitesDone": true, "prerequisitesProgress": { "done": 1, "total": 1 }, "threshold": { "status": "below", "window": "calendar_year_current_or_previous", "measure": "eu_cross_border_b2c", "currentWindow": "2026", "previousWindow": "2025", "threshold": { "amount": "10000000000", "currency": "EUR" }, "current": { "amount": "8500000000", "currency": "EUR" }, "previous": { "amount": "0", "currency": "EUR" }, "transactionThreshold": null, "currentTransactions": null, "previousTransactions": null, "worldwideTurnoverDeclared": null, "ratioPpm": "850000", "percent": 85, "detail": "8500.00 EUR counted (earlier window 0.00) against 10000.00 EUR" }, "timeZones": ["Europe/Zagreb"], "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" }, { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xm", "object": "registration", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "HR_DOMESTIC", "regimeName": "Croatia, domestic VAT", "jurisdictionIds": ["HR"], "state": "registered", "stateReason": "home_country", "stateChangedAt": "2026-10-13T12:00:00.000Z", "armed": false, "triggeredAt": null, "deadlineAt": null, "autoBlockAt": null, "applicationSubmittedAt": null, "escalationLevel": 0, "registrationNumber": "HR12345678901", "effectiveFrom": null, "registeredAt": null, "prerequisitesDone": false, "prerequisitesProgress": { "done": 0, "total": 2 }, "threshold": null, "timeZones": ["Europe/Zagreb"], "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" } ], "has_more": true, "next_cursor": "regn_01m4tx5nj8emwbyf7y9vcf47xm" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or the page size is malformed (`details.issues`). | 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`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't see this entity's registrations (brand-scoped members never can). | 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), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`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).