> ## 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 Listings

> Read the listings of the dealers your key can reach

Returns the listings of the dealers your key can reach, newest change first. This includes listings those dealers created in other ways (in the Okasie dashboard or through another feed): your own listings are the ones with your `externalReference` and the `externalProvider` value you see on them.

Any valid API key can call this endpoint; no write scope is needed.

## Query parameters

Invalid values do not cause an error: they fall back to the default or are ignored.

**page** `integer` (default: 1)

Page number, starting at 1. Also accepted as `page_number`. A page past the end returns an empty `data` array.

**pageSize** `integer` (default: 50)

Items per page, 1 to 200. Larger values are lowered to 200. Also accepted as `page_size` and `limit`.

**status** `string` (default: active)

`active`, `pending`, `sold`, `draft`, or `all` for every status. Any other value (also `inactive`) falls back to `active`. Listings that were deleted have status `inactive` and only appear with `all`.

**updatedSince** `string`

Only listings changed at or after this moment, as an ISO 8601 date-time, for example `2026-11-01T00:00:00Z`. Also accepted as `updated_since`. An unparseable value is ignored.

**locationCode** `string`

Only the listings of the dealer with this Dealer ID, for example `OK-00148` (exact match first, then case-insensitive). Also accepted as `location_code`.

**dealerId** `string`

Only the listings of this dealer profile UUID. Also accepted as `locationId`, `profileId` and `userId`. A value that is not a UUID is ignored.

**parentDealerId** `string`

Only the listings of this dealer UUID and all its child locations. Also accepted as `parentId` and `companyId`. A value that is not a UUID is ignored.

A filter for a dealer outside your access returns an empty list.

## Response

HTTP 200 with the [rate limit headers](https://docs.okasie.be/rate-limiting.md).

**data** `object[]`

The listings. Fields without a value are `null`.

**listing properties**

**id** `string`

Okasie listing UUID.

**slug** `string`

URL slug of the listing.

**listingUrl** `string`

Public page of the listing. Set for every status, but the page is only public while `status` is `active`.

**dealerProfileId** `string`

Dealer profile UUID.

**externalReference** `string | null`

The reference of the partner that created it, `null` for listings created in the dashboard.

**externalProvider** `string | null`

Identifies the partner key or feed that created the listing.

**title** `string`

Title.

**description** `string | null`

Description.

**status** `string`

`active`, `pending`, `sold`, `draft`, or `inactive` (deleted).

**price** `number | null`

Asking price.

**currency** `string`

Always `EUR`.

**brand** `string | null`

Make.

**model** `string | null`

Model.

**variant** `string | null`

Version or trim (`variant` or `customType` on input).

**year** `integer | null`

Model year.

**firstRegistration** `string | null`

First registration, as sent.

**mileage** `integer | null`

Odometer reading in km.

**fuelType** `string | null`

Okasie label, for example `Benzine`.

**transmission** `string | null`

Okasie label, for example `Automaat`.

**bodyType** `string | null`

Okasie label, for example `Hatchback`.

**color** `string | null`

Exterior colour.

**doors** `integer | null`

Doors.

**seats** `integer | null`

Seats.

**powerKw** `integer | null`

Power in whole kW.

**engine** `string | null`

Engine displacement in litres.

**co2Emission** `integer | null`

CO2 in g/km.

**co2Type** `string | null`

CO2 test cycle.

**emissionClass** `string | null`

Euro norm.

**fuelConsumption** `number | null`

l/100 km.

**driveType** `string | null`

Drive type.

**gears** `integer | null`

Gears.

**interiorColor** `string | null`

Interior colour.

**interiorMaterial** `string | null`

Interior material.

**paintType** `string | null`

Paint type.

**weight** `integer | null`

Weight in kg.

**previousOwners** `integer | null`

Previous owners.

**serviceHistory** `boolean | null`

Maintenance history available.

**warranty** `boolean | null`

Sold with warranty.

**warrantyMonths** `integer | null`

Warranty in months.

**vehicleType** `string | null`

VAT regime, for example `margin`.

**conditionTags** `string[] | null`

Condition tags (`conditionTags` or `condition` on input).

**vin** `string | null`

Chassis number.

**carPassUrl** `string | null`

Car-Pass URL or 11-digit certificate number.

**location** `object`

`postalCode`, `city`, `province`, `latitude`, `longitude`.

**images** `object[]`

Photos as hosted by Okasie, sorted by position: `url`, `position`.

**mainImageUrl** `string | null`

URL of the first photo.

**features** `object[]`

`category`, `name`.

**dealer** `object`

The dealer: `id`, `parentId`, `locationCode` (Dealer ID), `companyName`, `fullName`, `displayName`, `email`, `phone`, `address`, `postalCode`, `city`, `province`, `logoUrl`, `metadata`, and `parent` (`id`, `locationCode`, `companyName`, `fullName`, `displayName`) or `null`.

**createdAt** `string`

ISO 8601.

**updatedAt** `string`

ISO 8601. Changes on every write by anyone, also by Okasie.

**soldAt** `string | null`

ISO 8601, set while the listing is sold.

**pagination** `object`

`page`, `pageSize`, `totalItems`, `totalPages`.

**meta** `object`

`partner` (`id`, `name`, `source`, `access`), `filters` (the filters as you sent them) and `profileScope` (`allowed`, `effective` and `filters`: the dealer UUIDs the query was limited to). See [Dealer access](https://docs.okasie.be/authentication.md#dealer-access) for `access`.

```bash cURL theme={null}
curl "https://www.okasie.be/api/external/v1/listings?locationCode=OK-00148&status=all&pageSize=200" \
  -H "Authorization: Bearer YOUR_API_SECRET"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "slug": "volkswagen-golf-1-5-tsi-life--0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "listingUrl": "https://www.okasie.be/aanbod/volkswagen-golf-1-5-tsi-life--0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "dealerProfileId": "7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f",
      "externalReference": "DV-123456",
      "externalProvider": "3a3a3a3a-3a3a-43a3-a3a3-3a3a3a3a3a3a",
      "title": "Volkswagen Golf 1.5 TSI Life",
      "description": "First owner, full dealer maintenance.",
      "status": "active",
      "price": 21950,
      "currency": "EUR",
      "brand": "Volkswagen",
      "model": "Golf",
      "year": 2022,
      "mileage": 38500,
      "fuelType": "Benzine",
      "transmission": "Automaat",
      "bodyType": "Hatchback",
      "color": "Grijs",
      "doors": 5,
      "seats": 5,
      "powerKw": 110,
      "co2Emission": 129,
      "emissionClass": "Euro 6d",
      "firstRegistration": "2022-03-15",
      "driveType": "FWD",
      "gears": 7,
      "interiorColor": "Zwart",
      "interiorMaterial": "Stof",
      "weight": 1310,
      "previousOwners": 1,
      "serviceHistory": true,
      "warranty": true,
      "warrantyMonths": 12,
      "co2Type": "WLTP",
      "paintType": "Metallic",
      "fuelConsumption": 5.7,
      "variant": "Life",
      "vehicleType": "margin",
      "conditionTags": ["Gebruikt"],
      "engine": "1.5",
      "vin": "WVWZZZCDZNW000000",
      "carPassUrl": null,
      "location": {
        "postalCode": "9000",
        "city": "Gent",
        "province": "Oost-Vlaanderen",
        "latitude": 51.0543,
        "longitude": 3.7174
      },
      "images": [
        {"url": "https://<okasie-storage>/listing-images/imports/.../0-1a2b3c4d5e6f7a8b.jpeg", "position": 0}
      ],
      "mainImageUrl": "https://<okasie-storage>/listing-images/imports/.../0-1a2b3c4d5e6f7a8b.jpeg",
      "features": [{"category": "comfort", "name": "Automatische airco"}],
      "dealer": {
        "id": "7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f",
        "parentId": null,
        "locationCode": "OK-00148",
        "companyName": "Example Cars BV",
        "fullName": null,
        "displayName": "Example Cars BV",
        "email": "sales@example.com",
        "phone": "+32 9 000 00 00",
        "address": "Voorbeeldstraat 1",
        "postalCode": "9000",
        "city": "Gent",
        "province": "Oost-Vlaanderen",
        "logoUrl": null,
        "metadata": {},
        "parent": null
      },
      "createdAt": "2026-11-01T09:12:01.000Z",
      "updatedAt": "2026-11-05T14:30:00.000Z",
      "soldAt": null
    }
  ],
  "pagination": {"page": 1, "pageSize": 200, "totalItems": 1, "totalPages": 1},
  "meta": {
    "partner": {
      "id": "your-partner-name",
      "name": "your-partner-name",
      "source": "database",
      "access": {
        "scope": "restricted",
        "rootProfileIds": ["7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f"],
        "profileIds": ["7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f"]
      }
    },
    "filters": {
      "status": "all",
      "updatedSince": null,
      "dealerId": null,
      "locationId": null,
      "parentDealerId": null,
      "locationCode": "OK-00148"
    },
    "profileScope": {
      "allowed": ["7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f"],
      "effective": ["7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f"],
      "filters": {"dealerId": null, "parentId": null, "locationCode": "OK-00148"}
    }
  }
}
```

## Errors

The read endpoints return a plain error body: `{"error": "<message>"}`.

| Status | Body | When |
| - | - | - |
| 401 | `{"error": "Unauthorized"}` | Missing or unknown API key |
| 429 | `{"error": "Too many requests"}` | Rate limit reached; see the `Retry-After` header |
| 500 | `{"error": "Failed to load listings"}` | Okasie could not read the listings; retry later |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.