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

# Create/Update Listing

> Create or update a vehicle listing

# Create or Update Listing

Upsert a vehicle listing by external reference. Creates a new listing if it doesn't exist, or updates the existing one.

<Note>
  Requires the `write:listings` scope. Contact support to enable write access.
</Note>

<Warning>
  **PUT is a full replacement**

  The PUT operation replaces the entire listing. Fields not included in your request will be set to `null`. Always send ALL fields with every request, even when updating an existing listing.
</Warning>

## Path Parameters

<ParamField path="externalReference" type="string" required>
  Your unique reference for this listing (max 64 characters)
</ParamField>

## Request Body

<Note>
  Use these JSON field names in API payloads. Dashboard HTML field names are not the API contract unless they are listed here as aliases.
</Note>

### Car-Pass / carpass

Use `carPassUrl` for Car-Pass. The search term `carpass` is intentionally listed here as an alias for partners who search without the hyphen. Accepted input aliases are `carPass`, `car_pass_url`, and `carPassNumber`, but new integrations should send `carPassUrl`.

### JSON Field Names

| Field                 | Required                                 | Description                                                                                                            |
| --------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `externalReference`   | Yes for bulk upsert                      | Your unique listing reference. For single upsert this is the path parameter                                            |
| `external_reference`  | Alias                                    | Accepted bulk upsert alias for `externalReference`; prefer `externalReference`                                         |
| `dealerProfileId`     | Yes, unless `dealerLocationCode` is used | Dealer profile UUID                                                                                                    |
| `dealerLocationCode`  | Yes, unless `dealerProfileId` is used    | Dealer location code from the Okasie dashboard                                                                         |
| `status`              | No                                       | `active`, `pending`, `sold`, or `draft`                                                                                |
| `title`               | Yes                                      | Listing title                                                                                                          |
| `description`         | No                                       | Listing description                                                                                                    |
| `price`               | Yes for `active`/`pending`               | Price in EUR                                                                                                           |
| `currency`            | No                                       | ISO 4217 currency code, defaults to `EUR`                                                                              |
| `brand`               | No                                       | Vehicle brand                                                                                                          |
| `model`               | No                                       | Vehicle model                                                                                                          |
| `variant`             | No                                       | Model variant or trim                                                                                                  |
| `customType`          | No                                       | Custom vehicle type label. Falls back to `variant` when omitted                                                        |
| `year`                | No                                       | Build year                                                                                                             |
| `mileage`             | No                                       | Mileage in kilometers                                                                                                  |
| `fuelType`            | No                                       | Fuel type                                                                                                              |
| `transmission`        | No                                       | Transmission type                                                                                                      |
| `bodyType`            | No                                       | Body type                                                                                                              |
| `engine`              | No                                       | Engine description                                                                                                     |
| `driveType`           | No                                       | Drive type                                                                                                             |
| `gears`               | No                                       | Number of gears                                                                                                        |
| `color`               | No                                       | Exterior color                                                                                                         |
| `interiorColor`       | No                                       | Interior color                                                                                                         |
| `interiorMaterial`    | No                                       | Interior material                                                                                                      |
| `doors`               | No                                       | Number of doors                                                                                                        |
| `seats`               | No                                       | Number of seats                                                                                                        |
| `powerKw`             | No                                       | Engine power in kW                                                                                                     |
| `weight`              | No                                       | Vehicle weight in kg                                                                                                   |
| `previousOwners`      | No                                       | Number of previous owners                                                                                              |
| `serviceHistory`      | No                                       | Whether service history is available                                                                                   |
| `warranty`            | No                                       | Whether warranty is included                                                                                           |
| `warrantyMonths`      | No                                       | Warranty duration in months                                                                                            |
| `co2Emission`         | No                                       | CO2 emissions in g/km                                                                                                  |
| `co2Type`             | No                                       | `WLTP` or `NEDC`                                                                                                       |
| `emissionClass`       | No                                       | Euro emission class                                                                                                    |
| `paintType`           | No                                       | Paint type                                                                                                             |
| `fuelConsumption`     | No                                       | Fuel consumption in L/100km                                                                                            |
| `condition`           | No                                       | Vehicle condition                                                                                                      |
| `conditionTags`       | No                                       | Array of condition tags, max 6                                                                                         |
| `vehicleType`         | No                                       | VAT regime: `margin` or `btw`                                                                                          |
| `firstRegistration`   | No                                       | First registration date, format `YYYY-MM`                                                                              |
| `vin`                 | No                                       | Vehicle identification number                                                                                          |
| `carPassUrl`          | No                                       | Preferred Car-Pass field. Accepts a `public.car-pass.be` or `car-pass.be` URL, or a legacy 11-digit certificate number |
| `carPass`             | Alias                                    | Accepted alias for `carPassUrl`; prefer `carPassUrl`                                                                   |
| `car_pass_url`        | Alias                                    | Accepted alias for `carPassUrl`; prefer `carPassUrl`                                                                   |
| `carPassNumber`       | Alias                                    | Accepted alias for `carPassUrl`; prefer `carPassUrl`                                                                   |
| `postalCode`          | Yes for active listings                  | Belgian postal code                                                                                                    |
| `city`                | Yes for active listings                  | City                                                                                                                   |
| `province`            | Yes for active listings                  | Province                                                                                                               |
| `latitude`            | No                                       | Latitude                                                                                                               |
| `longitude`           | No                                       | Longitude                                                                                                              |
| `location.postalCode` | No                                       | Nested location postal code alternative                                                                                |
| `location.city`       | No                                       | Nested location city alternative                                                                                       |
| `location.province`   | No                                       | Nested location province alternative                                                                                   |
| `location.latitude`   | No                                       | Nested location latitude alternative                                                                                   |
| `location.longitude`  | No                                       | Nested location longitude alternative                                                                                  |
| `features[].category` | No                                       | Feature category                                                                                                       |
| `features[].name`     | No                                       | Feature name                                                                                                           |
| `features[].feature`  | No                                       | Accepted alias for feature name                                                                                        |
| `images[]`            | No                                       | Image URL string                                                                                                       |
| `images[].url`        | No                                       | Image URL                                                                                                              |
| `images[].imageUrl`   | No                                       | Accepted alias for `images[].url`                                                                                      |
| `images[].position`   | No                                       | Image order                                                                                                            |

<ParamField body="dealerProfileId" type="string">
  Dealer profile UUID. Required if `dealerLocationCode` is not provided.
</ParamField>

<ParamField body="dealerLocationCode" type="string">
  Location code. Required if `dealerProfileId` is not provided.
</ParamField>

<ParamField body="status" default="draft" type="string">
  Listing status: `active`, `pending`, `sold`, or `draft`
</ParamField>

<ParamField body="title" type="string" required>
  Listing title
</ParamField>

<ParamField body="description" type="string">
  Detailed description (max 15,000 characters)
</ParamField>

<ParamField body="price" type="number">
  Price in EUR. Required when status is `active` or `pending`.
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code. Defaults to `EUR`.
</ParamField>

<ParamField body="brand" type="string">
  Vehicle brand (e.g., "Opel", "Volkswagen")
</ParamField>

<ParamField body="model" type="string">
  Vehicle model (e.g., "Corsa", "Golf")
</ParamField>

<ParamField body="year" type="integer">
  Build year (1900 - current year + 1)
</ParamField>

<ParamField body="mileage" type="integer">
  Kilometers driven
</ParamField>

<ParamField body="fuelType" type="string">
  Fuel type: `petrol`, `diesel`, `electric`, `hybrid`, `lpg`, `cng`, `other`
</ParamField>

<ParamField body="transmission" type="string">
  Transmission: `manual`, `automatic`, `semi-automatic`, `other`
</ParamField>

<ParamField body="bodyType" type="string">
  Body type: `hatchback`, `sedan`, `suv`, `wagon`, `convertible`, `van`, `coupe`, `other`
</ParamField>

<ParamField body="variant" type="string">
  Model variant/trim level (e.g., "GT Line", "Signature")
</ParamField>

<ParamField body="customType" type="string">
  Custom vehicle type label. If omitted, `variant` is also used as the custom type label.
</ParamField>

<ParamField body="engine" type="string">
  Engine description (e.g., "1.6 TDI 115pk", "2.0 TSI")
</ParamField>

<ParamField body="driveType" type="string">
  Drive type: `FWD`, `RWD`, `AWD`, `4WD`, `4x4`
</ParamField>

<ParamField body="gears" type="integer">
  Number of gears (1-12)
</ParamField>

<ParamField body="color" type="string">
  Exterior color
</ParamField>

<ParamField body="interiorColor" type="string">
  Interior color
</ParamField>

<ParamField body="interiorMaterial" type="string">
  Interior material: `Leder`, `Stof`, `Alcantara`, `Kunstleder`, `Leder/Stof`, `Leder/Alcantara`
</ParamField>

<ParamField body="weight" type="integer">
  Vehicle weight in kg
</ParamField>

<ParamField body="previousOwners" type="integer">
  Number of previous owners
</ParamField>

<ParamField body="serviceHistory" type="boolean">
  Service history available
</ParamField>

<ParamField body="warranty" type="boolean">
  Warranty included
</ParamField>

<ParamField body="warrantyMonths" type="integer">
  Warranty duration in months
</ParamField>

<ParamField body="co2Emission" type="integer">
  CO2 emissions in g/km
</ParamField>

<ParamField body="co2Type" type="string">
  CO2 measurement standard: `WLTP` or `NEDC`
</ParamField>

<ParamField body="emissionClass" type="string">
  Euro emission class (e.g., "Euro 6d")
</ParamField>

<ParamField body="paintType" type="string">
  Paint type: `Metallic`, `Parelmoer`, `Mat`, `Uni`
</ParamField>

<ParamField body="fuelConsumption" type="number">
  Fuel consumption in L/100km
</ParamField>

<ParamField body="condition" type="string">
  Vehicle condition: `new`, `used`, `demo`, `oldtimer`, `damaged`
</ParamField>

<ParamField body="conditionTags" type="array">
  Array of condition tag strings (max 6)
</ParamField>

<ParamField body="vehicleType" type="string">
  VAT regime: `margin` or `btw`
</ParamField>

<ParamField body="firstRegistration" type="string">
  First registration date (format: YYYY-MM)
</ParamField>

<ParamField body="doors" type="integer">
  Number of doors (1-10)
</ParamField>

<ParamField body="seats" type="integer">
  Number of seats (1-10)
</ParamField>

<ParamField body="powerKw" type="number">
  Engine power in kW
</ParamField>

<ParamField body="vin" type="string">
  Vehicle identification number
</ParamField>

<ParamField body="carPassUrl" type="string">
  Public Car-Pass URL from `public.car-pass.be` or `car-pass.be`, or a legacy 11-digit certificate number. Input aliases `carPass`, `car_pass_url`, and `carPassNumber` are also accepted.
</ParamField>

<ParamField body="postalCode" type="string">
  Belgian postal code. Required for active listings.
</ParamField>

<ParamField body="city" type="string">
  City name. Required for active listings.
</ParamField>

<ParamField body="province" type="string">
  Province name. Required for active listings.
</ParamField>

<ParamField body="latitude" type="number">
  Location latitude. Can also be sent as `location.latitude`.
</ParamField>

<ParamField body="longitude" type="number">
  Location longitude. Can also be sent as `location.longitude`.
</ParamField>

<ParamField body="location" type="object">
  Optional nested location object with `postalCode`, `city`, `province`, `latitude`, and `longitude`.
</ParamField>

<ParamField body="features" type="array">
  Array of feature objects with `category` and `name`. `feature` is accepted as an alias for `name`.
</ParamField>

<ParamField body="images" type="array">
  Array of image URLs or objects with `url`/`imageUrl` and `position`. Images are automatically mirrored to Okasie storage.
</ParamField>

## Response

<ResponseField name="data.listingId" type="string">
  Okasie listing UUID
</ResponseField>

<ResponseField name="data.externalReference" type="string">
  Your provided reference
</ResponseField>

<ResponseField name="data.status" type="string">
  Current listing status
</ResponseField>

<ResponseField name="data.created" type="boolean">
  `true` if newly created, `false` if updated
</ResponseField>

<ResponseField name="data.warnings" type="object">
  Optional warnings (e.g., skipped images)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://www.okasie.be/api/external/v1/listings/MY-REF-001" \
    -H "Authorization: Bearer YOUR_API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "dealerProfileId": "84118503-030b-45f3-a867-c77d54d00b4c",
      "status": "active",
      "title": "Opel Corsa 1.2 Turbo GS Line",
      "description": "Compact city car in excellent condition",
      "price": 19995,
      "brand": "Opel",
      "model": "Corsa",
      "variant": "GS Line",
      "year": 2021,
      "mileage": 25000,
      "fuelType": "petrol",
      "transmission": "automatic",
      "driveType": "FWD",
      "gears": 6,
      "bodyType": "hatchback",
      "engine": "1.2 Turbo 100pk",
      "color": "Blauw",
      "interiorColor": "Zwart",
      "interiorMaterial": "Stof",
      "doors": 5,
      "seats": 5,
      "powerKw": 74,
      "weight": 1180,
      "previousOwners": 1,
      "serviceHistory": true,
      "warranty": true,
      "warrantyMonths": 12,
      "co2Emission": 118,
      "co2Type": "WLTP",
      "emissionClass": "Euro 6d",
      "paintType": "Metallic",
      "fuelConsumption": 5.1,
      "condition": "used",
      "vehicleType": "margin",
      "firstRegistration": "2021-03",
      "carPassUrl": "https://public.car-pass.be/vhr/example",
      "postalCode": "9000",
      "city": "Gent",
      "province": "Oost-Vlaanderen",
      "features": [
        {"category": "comfort", "name": "Airconditioning"},
        {"category": "safety", "name": "ABS"}
      ],
      "images": [
        "https://partner.example/car1.jpg",
        {"url": "https://partner.example/car2.jpg", "position": 1}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success (201 Created) theme={null}
  {
    "data": {
      "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "externalReference": "MY-REF-001",
      "status": "active",
      "created": true
    }
  }
  ```

  ```json Updated (200 OK) theme={null}
  {
    "data": {
      "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "externalReference": "MY-REF-001",
      "status": "active",
      "created": false
    }
  }
  ```

  ```json With Warnings theme={null}
  {
    "data": {
      "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
      "externalReference": "MY-REF-001",
      "status": "active",
      "created": true,
      "warnings": {
        "skippedImages": [
          {"source": "https://broken-url.com/image.jpg", "reason": "mirror_failed"}
        ]
      }
    }
  }
  ```
</ResponseExample>

## Error Responses

| Status | Code                | Description                                    |
| ------ | ------------------- | ---------------------------------------------- |
| 400    | `INVALID_TITLE`     | Title is required                              |
| 400    | `INVALID_PRICE`     | Price required for active listings             |
| 400    | `INVALID_LOCATION`  | postalCode, city, and province required        |
| 400    | `INVALID_PROFILE`   | dealerProfileId or dealerLocationCode required |
| 403    | `PROFILE_FORBIDDEN` | No access to requested profile                 |
| 422    | `VALIDATION_FAILED` | Payload validation failed                      |

## Enum Values Reference

### driveType

| Value | Description                              |
| ----- | ---------------------------------------- |
| `FWD` | Front-wheel drive (Voorwielaandrijving)  |
| `RWD` | Rear-wheel drive (Achterwielaandrijving) |
| `AWD` | All-wheel drive (Vierwielaandrijving)    |
| `4WD` | Four-wheel drive                         |
| `4x4` | Four-wheel drive                         |

### interiorMaterial

| Value             | Description                   |
| ----------------- | ----------------------------- |
| `Leder`           | Leather                       |
| `Stof`            | Fabric                        |
| `Alcantara`       | Alcantara                     |
| `Kunstleder`      | Synthetic leather             |
| `Leder/Stof`      | Leather/Fabric combination    |
| `Leder/Alcantara` | Leather/Alcantara combination |

### paintType

| Value       | Description       |
| ----------- | ----------------- |
| `Metallic`  | Metallic paint    |
| `Parelmoer` | Pearl paint       |
| `Mat`       | Matte paint       |
| `Uni`       | Solid/plain paint |

### co2Type

| Value  | Description                                       |
| ------ | ------------------------------------------------- |
| `WLTP` | Worldwide Harmonised Light Vehicle Test Procedure |
| `NEDC` | New European Driving Cycle (legacy)               |

### condition

| Value      | Description             |
| ---------- | ----------------------- |
| `new`      | New vehicle             |
| `used`     | Used vehicle            |
| `demo`     | Demo/showroom vehicle   |
| `oldtimer` | Classic/vintage vehicle |
| `damaged`  | Damaged vehicle         |

### vehicleType

| Value    | Description                       |
| -------- | --------------------------------- |
| `margin` | Margin scheme (no VAT deductible) |
| `btw`    | VAT scheme (VAT deductible)       |