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

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

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

externalReference

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

dealerProfileId

string

Dealer profile UUID. Required if dealerLocationCode is not provided.

dealerLocationCode

string

Location code. Required if dealerProfileId is not provided.

status

string

default:"draft"

Listing status: active, pending, sold, or draft

title

string

required

Listing title

description

string

Detailed description (max 15,000 characters)

price

number

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

currency

string

ISO 4217 currency code. Defaults to EUR.

brand

string

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

model

string

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

year

integer

Build year (1900 - current year + 1)

mileage

integer

Kilometers driven

fuelType

string

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

transmission

string

Transmission: manual, automatic, semi-automatic, other

bodyType

string

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

variant

string

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

customType

string

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

engine

string

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

driveType

string

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

gears

integer

Number of gears (1-12)

color

string

Exterior color

interiorColor

string

Interior color

interiorMaterial

string

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

weight

integer

Vehicle weight in kg

previousOwners

integer

Number of previous owners

serviceHistory

boolean

Service history available

warranty

boolean

Warranty included

warrantyMonths

integer

Warranty duration in months

co2Emission

integer

CO2 emissions in g/km

co2Type

string

CO2 measurement standard: WLTP or NEDC

emissionClass

string

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

paintType

string

Paint type: Metallic, Parelmoer, Mat, Uni

fuelConsumption

number

Fuel consumption in L/100km

condition

string

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

conditionTags

array

Array of condition tag strings (max 6)

vehicleType

string

VAT regime: margin or btw

firstRegistration

string

First registration date (format: YYYY-MM)

doors

integer

Number of doors (1-10)

seats

integer

Number of seats (1-10)

powerKw

number

Engine power in kW

vin

string

Vehicle identification number

carPassUrl

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.

postalCode

string

Belgian postal code. Required for active listings.

city

string

City name. Required for active listings.

province

string

Province name. Required for active listings.

latitude

number

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

longitude

number

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

location

object

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

features

array

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

images

array

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

Response

data.listingId

string

Okasie listing UUID

data.externalReference

string

Your provided reference

data.status

string

Current listing status

data.created

boolean

true if newly created, false if updated

data.warnings

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

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)

List Listings Bulk Create/Update Listings

​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