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}
    ]
  }'

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": true
  }
}

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": false
  }
}

{
  "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"}
      ]
    }
  }
}

PUT

api

external

listings

{externalReference}

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}
    ]
  }'

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": true
  }
}

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": false
  }
}

{
  "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"}
      ]
    }
  }
}

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.

Requires the write:listings scope. Contact support to enable write access.

PUT is a full replacementThe 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.

Path Parameters

string

required

Your unique reference for this listing (max 64 characters)

Request Body

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

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

string

Dealer profile UUID. Required if dealerLocationCode is not provided.

string

Location code. Required if dealerProfileId is not provided.

string

default:"draft"

Listing status: active, pending, sold, or draft

string

required

Listing title

string

Detailed description (max 15,000 characters)

number

Price in EUR. Required when status is active or pending.

string

ISO 4217 currency code. Defaults to EUR.

string

Vehicle brand (e.g., “Opel”, “Volkswagen”)

string

Vehicle model (e.g., “Corsa”, “Golf”)

integer

Build year (1900 - current year + 1)

integer

Kilometers driven

string

Fuel type: petrol, diesel, electric, hybrid, lpg, cng, other

string

Transmission: manual, automatic, semi-automatic, other

string

Body type: hatchback, sedan, suv, wagon, convertible, van, coupe, other

string

Model variant/trim level (e.g., “GT Line”, “Signature”)

string

Custom vehicle type label. If omitted, variant is also used as the custom type label.

string

Engine description (e.g., “1.6 TDI 115pk”, “2.0 TSI”)

string

Drive type: FWD, RWD, AWD, 4WD, 4x4

integer

Number of gears (1-12)

string

Exterior color

string

Interior color

string

Interior material: Leder, Stof, Alcantara, Kunstleder, Leder/Stof, Leder/Alcantara

integer

Vehicle weight in kg

integer

Number of previous owners

boolean

Service history available

boolean

Warranty included

integer

Warranty duration in months

integer

CO2 emissions in g/km

string

CO2 measurement standard: WLTP or NEDC

string

Euro emission class (e.g., “Euro 6d”)

string

Paint type: Metallic, Parelmoer, Mat, Uni

number

Fuel consumption in L/100km

string

Vehicle condition: new, used, demo, oldtimer, damaged

array

Array of condition tag strings (max 6)

string

VAT regime: margin or btw

string

First registration date (format: YYYY-MM)

integer

Number of doors (1-10)

integer

Number of seats (1-10)

number

Engine power in kW

string

Vehicle identification number

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.

string

Belgian postal code. Required for active listings.

string

City name. Required for active listings.

string

Province name. Required for active listings.

number

Location latitude. Can also be sent as location.latitude.

number

Location longitude. Can also be sent as location.longitude.

object

Optional nested location object with postalCode, city, province, latitude, and longitude.

array

Array of feature objects with category and name. feature is accepted as an alias for name.

array

Array of image URLs or objects with url/imageUrl and position. Images are automatically mirrored to Okasie storage.

Response

string

Okasie listing UUID

string

Your provided reference

string

Current listing status

boolean

true if newly created, false if updated

object

Optional warnings (e.g., skipped images)

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}
    ]
  }'

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": true
  }
}

{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": false
  }
}

{
  "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"}
      ]
    }
  }
}

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)

Overview

Listings

Locations

Create/Update Listing

Create or Update Listing

Path Parameters

Request Body

Car-Pass / carpass

JSON Field Names

Response

Error Responses

Enum Values Reference

driveType

interiorMaterial

paintType

co2Type

condition

vehicleType

​Create or Update Listing

​Path Parameters

​Request Body

​Car-Pass / carpass

​JSON Field Names

​Response

​Error Responses

​Enum Values Reference

​driveType

​interiorMaterial

​paintType

​co2Type

​condition

​vehicleType

Create or Update Listing

Path Parameters

Request Body

Car-Pass / carpass

JSON Field Names

Response

Error Responses

Enum Values Reference

driveType

interiorMaterial

paintType

co2Type

condition

vehicleType