> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Spaces

> List the spaces (sub-divisions) in your organization

# List Spaces

Returns a paginated list of the **active** spaces in your organization.

A space is a sub-division of an organization for running separate events —
different cities, brands, teams, or (for a marketplace) sellers. Every event,
experience, and contact belongs to a space and references it by its
`identifier` (the `space_identifier` field on other endpoints).

The organization-wide **`GENERAL`** scope is synthetic — it is not a persisted
space and does not appear in this list. Target it elsewhere by omitting
`space_identifier`.

Requires the `spaces:read` scope.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (starts at 1).
</ParamField>

<ParamField query="page_size" type="integer" default="50">
  Number of spaces per page. Maximum: `200`.
</ParamField>

## Response

<ResponseField name="data" type="array">
  <Expandable title="Space object">
    <ResponseField name="id" type="string">Unique space identifier (document ID)</ResponseField>
    <ResponseField name="identifier" type="string | null">The human-set slug used as `space_identifier` elsewhere</ResponseField>
    <ResponseField name="name" type="string | null">Display name</ResponseField>
    <ResponseField name="status" type="string | null">`active`</ResponseField>
    <ResponseField name="color" type="string | null">Accent color token</ResponseField>
    <ResponseField name="icon" type="string | null">Icon name or emoji</ResponseField>
    <ResponseField name="icon_type" type="string | null">`emoji` or `icon`</ResponseField>
    <ResponseField name="email" type="string | null">Contact email shown on receipts</ResponseField>

    <ResponseField name="linkedin" type="string | null" />

    <ResponseField name="instagram" type="string | null" />

    <ResponseField name="facebook" type="string | null" />

    <ResponseField name="twitter" type="string | null" />

    <ResponseField name="website" type="string | null" />

    <ResponseField name="tax_details" type="object | null">
      <Expandable>
        <ResponseField name="tax_type" type="string | null">`VAT` or `Sales Tax`</ResponseField>

        <ResponseField name="vat_number" type="string | null" />

        <ResponseField name="vat_rate" type="number | null">Percentage (0–100)</ResponseField>

        <ResponseField name="legal_entity_name" type="string | null" />

        <ResponseField name="legal_entity_address" type="string | null" />

        <ResponseField name="country" type="string | null" />

        <ResponseField name="is_eu" type="boolean | null" />

        <ResponseField name="is_valid_vat_number" type="boolean | null" />

        <ResponseField name="notes_on_receipts" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string | null">ISO 8601 creation timestamp</ResponseField>
    <ResponseField name="updated_at" type="string | null">ISO 8601 last-updated timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable>
    <ResponseField name="total" type="integer">Total number of active spaces</ResponseField>
    <ResponseField name="page" type="integer">Current page number</ResponseField>
    <ResponseField name="page_size" type="integer">Items per page</ResponseField>
    <ResponseField name="total_pages" type="integer">Total number of pages</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-KEY: your_api_key" \
    "https://www.gomry.com/api/v1/spaces?page=1&page_size=20"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://www.gomry.com/api/v1/spaces?page=1&page_size=20",
    { headers: { "X-API-KEY": "your_api_key" } }
  );
  const { data, pagination } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "AbCdEfGhIjKlMnOpQrSt",
        "identifier": "milan",
        "name": "Milan",
        "status": "active",
        "color": "zinc",
        "icon": "general",
        "icon_type": "emoji",
        "email": "milan@acme.com",
        "linkedin": null,
        "instagram": null,
        "facebook": null,
        "twitter": null,
        "website": null,
        "tax_details": {
          "tax_type": "VAT",
          "vat_number": "IT12345678901",
          "vat_rate": 22,
          "legal_entity_name": "ACME Milan SRL",
          "legal_entity_address": "Via Roma 1, 20121 Milano",
          "country": "IT",
          "is_eu": true,
          "is_valid_vat_number": true,
          "notes_on_receipts": null
        },
        "created_at": "2025-03-01T10:00:00.000Z",
        "updated_at": "2025-06-20T15:30:00.000Z"
      }
    ],
    "pagination": { "total": 1, "page": 1, "page_size": 20, "total_pages": 1 }
  }
  ```
</ResponseExample>