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

# List Locations

> Retrieve dealer locations within your access scope

# List Locations

Retrieve dealer locations within your partner access scope. Supports hierarchical queries and optional listing counts.

## Query Parameters

<ParamField query="parentId" type="string">
  Filter to locations under this parent profile UUID. Alias: `parent_id`
</ParamField>

<ParamField query="includeChildren" type="boolean" default="true">
  Include child locations in the result set
</ParamField>

<ParamField query="withCounts" type="boolean" default="true">
  Include listing counts per location
</ParamField>

<ParamField query="search" type="string">
  Search by name, city, province, or location code
</ParamField>

## Response

### Location Response Field Names

| Field                      | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `id`                       | Location profile UUID                                  |
| `parentId`                 | Parent location UUID                                   |
| `isRoot`                   | Whether this location is in the partner root scope     |
| `locationCode`             | Unique location code                                   |
| `companyName`              | Company name                                           |
| `fullName`                 | Full profile name                                      |
| `displayName`              | Display name                                           |
| `email`                    | Contact email                                          |
| `phone`                    | Contact phone                                          |
| `address`                  | Street address                                         |
| `postalCode`               | Postal code                                            |
| `city`                     | City                                                   |
| `province`                 | Province                                               |
| `logoUrl`                  | Logo URL                                               |
| `metadata`                 | Location metadata                                      |
| `parent.id`                | Parent profile UUID                                    |
| `parent.locationCode`      | Parent location code                                   |
| `parent.companyName`       | Parent company name                                    |
| `parent.fullName`          | Parent full name                                       |
| `parent.displayName`       | Parent display name                                    |
| `stats.activeListings`     | Active listing count                                   |
| `stats.totalListings`      | Total listing count                                    |
| `stats.avgActivePrevMonth` | Average active listings previous month, when available |
| `updatedAt`                | ISO 8601 last update timestamp                         |
| `meta.total`               | Number of returned locations                           |
| `meta.profileIds`          | Effective profile IDs in response scope                |
| `meta.rootProfileIds`      | Partner root profile IDs, when available               |
| `meta.filters.parentId`    | Applied parent filter                                  |
| `meta.filters.search`      | Applied search filter                                  |
| `meta.partner`             | Partner metadata                                       |

<ResponseField name="data" type="array">
  Array of location objects

  <Expandable title="Location properties">
    <ResponseField name="id" type="string">
      Location profile UUID
    </ResponseField>

    <ResponseField name="parentId" type="string">
      Parent location UUID (null for root)
    </ResponseField>

    <ResponseField name="locationCode" type="string">
      Unique location code
    </ResponseField>

    <ResponseField name="companyName" type="string">
      Legal company name
    </ResponseField>

    <ResponseField name="fullName" type="string">
      Full profile name
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Display name
    </ResponseField>

    <ResponseField name="email" type="string">
      Contact email
    </ResponseField>

    <ResponseField name="phone" type="string">
      Contact phone
    </ResponseField>

    <ResponseField name="address" type="string">
      Street address
    </ResponseField>

    <ResponseField name="postalCode" type="string">
      Postal code
    </ResponseField>

    <ResponseField name="city" type="string">
      City
    </ResponseField>

    <ResponseField name="province" type="string">
      Province
    </ResponseField>

    <ResponseField name="logoUrl" type="string">
      Logo URL
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Location metadata
    </ResponseField>

    <ResponseField name="parent" type="object">
      Parent profile summary
    </ResponseField>

    <ResponseField name="isRoot" type="boolean">
      True if this is a root/parent location
    </ResponseField>

    <ResponseField name="stats" type="object">
      Listing statistics (when withCounts=true)
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last update timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Request metadata including partner info
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://www.okasie.be/api/external/v1/locations?withCounts=true" \
    -H "Authorization: Bearer YOUR_API_SECRET"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://www.okasie.be/api/external/v1/locations?withCounts=true",
    {
      headers: {
        Authorization: `Bearer ${process.env.PARTNER_SECRET}`,
      },
    }
  );

  const data = await response.json();
  data.data.forEach(location => {
    console.log(`${location.displayName}: ${location.stats?.activeListings} listings`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": [
      {
        "id": "8f8f8f8f-8f8f-408f-a8f8-8f8f8f8f8f8f",
        "parentId": null,
        "locationCode": "DEX-HQ",
        "companyName": "DEX Belgium NV",
        "fullName": "DEX Belgium",
        "displayName": "DEX Belgium",
        "email": "info@dex.be",
        "phone": "+32 3 123 45 67",
        "address": "Hoofdstraat 1",
        "postalCode": "2000",
        "city": "Antwerpen",
        "province": "Antwerpen",
        "logoUrl": "https://cdn.okasie.be/logos/dex.png",
        "metadata": {},
        "parent": null,
        "isRoot": true,
        "stats": {
          "activeListings": 250,
          "totalListings": 312,
          "avgActivePrevMonth": 238.5
        },
        "updatedAt": "2024-10-05T09:12:01Z"
      }
    ],
    "meta": {
      "total": 5,
      "profileIds": ["8f8f8f8f-8f8f-408f-a8f8-8f8f8f8f8f8f"],
      "rootProfileIds": ["8f8f8f8f-8f8f-408f-a8f8-8f8f8f8f8f8f"],
      "filters": {
        "parentId": null,
        "search": null
      },
      "partner": {
        "id": "partner-id",
        "name": "Partner Name"
      }
    }
  }
  ```
</ResponseExample>

## Error Responses

| Status | Code           | Description                |
| ------ | -------------- | -------------------------- |
| 401    | `UNAUTHORIZED` | Invalid or missing API key |
| 500    | `SERVER_ERROR` | Failed to load locations   |