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

> Retrieve paginated vehicle listings

# List Listings

Retrieve a paginated list of vehicle listings within your partner access scope.

<ParamField query="page" default="1" type="integer">
  Page number (1-based). Alias: `page_number`
</ParamField>

<ParamField query="pageSize" default="50" type="integer">
  Number of items per page (max 200). Aliases: `page_size`, `limit`
</ParamField>

<ParamField query="status" default="active" type="string">
  Filter by listing status: `active`, `pending`, `sold`, `draft`, or `all`
</ParamField>

<ParamField query="updatedSince" type="string">
  ISO 8601 datetime for incremental sync (e.g., `2024-10-01T00:00:00Z`). Alias: `updated_since`
</ParamField>

<ParamField query="dealerId" type="string">
  Filter by specific dealer profile UUID
</ParamField>

<ParamField query="locationId" type="string">
  Alias for filtering by a specific dealer/location profile UUID
</ParamField>

<ParamField query="profileId" type="string">
  Alias for filtering by a specific dealer/location profile UUID. Alias: `userId`
</ParamField>

<ParamField query="parentDealerId" type="string">
  Filter by parent dealer (includes all child locations). Aliases: `parentId`, `companyId`
</ParamField>

<ParamField query="locationCode" type="string">
  Filter by location code (case-insensitive). Alias: `location_code`
</ParamField>

## Response

### Listing Response Field Names

| Field                 | Description                                               |
| --------------------- | --------------------------------------------------------- |
| `id`                  | Okasie listing UUID                                       |
| `slug`                | Public Okasie listing slug                                |
| `listingUrl`          | Public Okasie listing URL                                 |
| `dealerProfileId`     | Dealer profile UUID                                       |
| `externalReference`   | Partner listing reference                                 |
| `externalProvider`    | Partner/provider identifier                               |
| `title`               | Listing title                                             |
| `description`         | Listing description                                       |
| `status`              | `active`, `pending`, `sold`, or `draft`                   |
| `price`               | Listing price                                             |
| `currency`            | Currency, currently `EUR`                                 |
| `brand`               | Vehicle brand                                             |
| `model`               | Vehicle model                                             |
| `year`                | Build year                                                |
| `mileage`             | Mileage in kilometers                                     |
| `fuelType`            | Fuel type                                                 |
| `transmission`        | Transmission type                                         |
| `bodyType`            | Body type                                                 |
| `color`               | Exterior color                                            |
| `doors`               | Number of doors                                           |
| `seats`               | Number of seats                                           |
| `powerKw`             | Engine power in kW                                        |
| `co2Emission`         | CO2 emissions in g/km                                     |
| `emissionClass`       | Euro emission class                                       |
| `firstRegistration`   | First registration date                                   |
| `driveType`           | Drive type                                                |
| `gears`               | Number of gears                                           |
| `interiorColor`       | Interior color                                            |
| `interiorMaterial`    | Interior material                                         |
| `weight`              | Vehicle weight in kg                                      |
| `previousOwners`      | Number of previous owners                                 |
| `serviceHistory`      | Whether service history is available                      |
| `warranty`            | Whether warranty is included                              |
| `warrantyMonths`      | Warranty duration in months                               |
| `co2Type`             | CO2 measurement standard                                  |
| `paintType`           | Paint type                                                |
| `fuelConsumption`     | Fuel consumption in L/100km                               |
| `variant`             | Model variant or trim                                     |
| `vehicleType`         | VAT regime                                                |
| `conditionTags`       | Vehicle condition tags                                    |
| `engine`              | Engine description                                        |
| `vin`                 | Vehicle identification number                             |
| `carPassUrl`          | Public Car-Pass URL or legacy 11-digit certificate number |
| `location.postalCode` | Listing postal code                                       |
| `location.city`       | Listing city                                              |
| `location.province`   | Listing province                                          |
| `location.latitude`   | Listing latitude                                          |
| `location.longitude`  | Listing longitude                                         |
| `images[].url`        | Image URL                                                 |
| `images[].position`   | Image order                                               |
| `mainImageUrl`        | First image URL                                           |
| `features[].category` | Feature category                                          |
| `features[].name`     | Feature name                                              |
| `dealer.id`           | Dealer profile UUID                                       |
| `dealer.parentId`     | Parent dealer profile UUID                                |
| `dealer.locationCode` | Dealer location code                                      |
| `dealer.companyName`  | Dealer company name                                       |
| `dealer.fullName`     | Dealer full name                                          |
| `dealer.displayName`  | Dealer display name                                       |
| `dealer.email`        | Dealer email                                              |
| `dealer.phone`        | Dealer phone                                              |
| `dealer.address`      | Dealer address                                            |
| `dealer.postalCode`   | Dealer postal code                                        |
| `dealer.city`         | Dealer city                                               |
| `dealer.province`     | Dealer province                                           |
| `dealer.logoUrl`      | Dealer logo URL                                           |
| `dealer.metadata`     | Dealer location metadata                                  |
| `dealer.parent`       | Parent dealer summary                                     |
| `createdAt`           | ISO 8601 creation timestamp                               |
| `updatedAt`           | ISO 8601 last update timestamp                            |
| `soldAt`              | ISO 8601 sold timestamp, when sold                        |

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

  <Expandable title="Listing object properties">
    <ResponseField name="id" type="string">
      Okasie listing UUID
    </ResponseField>

    <ResponseField name="slug" type="string">
      Public Okasie listing slug
    </ResponseField>

    <ResponseField name="listingUrl" type="string">
      Public Okasie listing URL
    </ResponseField>

    <ResponseField name="dealerProfileId" type="string">
      Dealer profile UUID
    </ResponseField>

    <ResponseField name="externalReference" type="string">
      Your unique reference
    </ResponseField>

    <ResponseField name="externalProvider" type="string">
      Partner/provider identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Listing title
    </ResponseField>

    <ResponseField name="status" type="string">
      `active`, `pending`, `sold`, or `draft`
    </ResponseField>

    <ResponseField name="price" type="number">
      Price in currency
    </ResponseField>

    <ResponseField name="currency" type="string">
      ISO 4217 currency code (default: EUR)
    </ResponseField>

    <ResponseField name="brand" type="string">
      Vehicle brand
    </ResponseField>

    <ResponseField name="model" type="string">
      Vehicle model
    </ResponseField>

    <ResponseField name="year" type="integer">
      Build year
    </ResponseField>

    <ResponseField name="mileage" type="integer">
      Kilometers
    </ResponseField>

    <ResponseField name="carPassUrl" type="string">
      Public Car-Pass URL or legacy 11-digit certificate number, when provided
    </ResponseField>

    <ResponseField name="location" type="object">
      Location details with `postalCode`, `city`, `province`, `latitude`, `longitude`
    </ResponseField>

    <ResponseField name="images" type="array">
      Array of image objects with `url` and `position`
    </ResponseField>

    <ResponseField name="mainImageUrl" type="string">
      First image URL
    </ResponseField>

    <ResponseField name="features" type="array">
      Array of feature objects with `category` and `name`
    </ResponseField>

    <ResponseField name="dealer" type="object">
      Dealer information
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp
    </ResponseField>

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

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination properties">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="pageSize" type="integer">
      Items per page
    </ResponseField>

    <ResponseField name="totalItems" type="integer">
      Total number of items
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://www.okasie.be/api/external/v1/listings?pageSize=50&status=active" \
    -H "Authorization: Bearer YOUR_API_SECRET"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "46c7f6c9-70f7-4f98-8c32-12f1a67c6f2e",
        "dealerProfileId": "7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f",
        "externalReference": "ref-123",
        "title": "Opel Corsa 1.2 Turbo",
        "status": "active",
        "price": 19995,
        "currency": "EUR",
        "brand": "Opel",
        "model": "Corsa",
        "year": 2021,
        "mileage": 25000,
        "fuelType": "petrol",
        "transmission": "automatic",
        "bodyType": "hatchback",
        "carPassUrl": "https://public.car-pass.be/vhr/example",
        "location": {
          "postalCode": "9000",
          "city": "Gent",
          "province": "Oost-Vlaanderen",
          "latitude": 51.0543,
          "longitude": 3.7174
        },
        "images": [
          {"url": "https://cdn.okasie.be/images/46c7f6c9/main.jpg", "position": 0}
        ],
        "dealer": {
          "id": "7f7f7f7f-7f7f-407f-a7f7-7f7f7f7f7f7f",
          "companyName": "Auto Gent",
          "locationCode": "DEX-GENT"
        },
        "createdAt": "2024-10-01T12:34:56Z",
        "updatedAt": "2024-10-05T09:12:01Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalItems": 123,
      "totalPages": 3
    },
    "meta": {
      "partner": {
        "id": "partner-id",
        "name": "Partner Name"
      }
    }
  }
  ```
</ResponseExample>