Mobeo API

A JSON API for managing your own adverts. Base URL: https://www.mobeo.co.uk/api/v1. All responses are {"success": true, "data": ...} or {"success": false, "error": {"code", "message", "details"}}.

Authentication

Create a key under Profile, API keys. Send it on every request as a header, either form:

X-API-KEY: mobeo_live_...
Authorization: Bearer mobeo_live_...

Send JSON bodies with Content-Type: application/json. Photo uploads use multipart/form-data.

Account

GET/me confirms the key and returns the account, whether it is a dealer, verification status, limits and how new adverts are published.

curl -H "X-API-KEY: $KEY" https://www.mobeo.co.uk/api/v1/me

Categories & attributes

GET/vehicle-categories lists categories (cars, vans, motorbikes, motorhomes, caravans...).

GET/vehicle-categories/{id} returns the attribute slugs you can send for that category, with the accepted options for selects. Use these slugs inside attributes when creating an advert. make, model, body and features are accepted for every category.

GET/vehicle-categories/{id}/models?make=Audi lists the models we know for a make. Send the model label exactly as returned.

Adverts

Call	What it does
GET/ads	Your adverts. Filters: status (live, pending_review, inactive, expired), external_ref, page, per_page (max 100).
GET/ads/{id}	One advert with attributes, declarations and photos.
POST/ads	Create an advert. Returns 201 with the advert and held_for_review.
PATCH/ads/{id}	Partial update. Only the fields you send change. status: "inactive" takes it offline, "live" brings it back.
DELETE/ads/{id}	Remove the advert. (POST /ads/{id}/delete works for clients that cannot send DELETE.)

Create an advert

curl -X POST https://www.mobeo.co.uk/api/v1/ads \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{
    "category": "cars",
    "heading": "2019 Audi A4 2.0 TDI S line, one owner, full Audi history",
    "description": "At least 40 words covering condition, service history, MOT, extras and why it is for sale ...",
    "price": 15995,
    "price_negotiable": true,
    "condition": "used",
    "location": "LS1 4AP",
    "registration": "AB19CDE",
    "attributes": {
      "make": "Audi", "model": "A4", "year": 2019, "mileage": 42000,
      "fuel": "Diesel", "transmission": "Automatic", "color": "Black",
      "body": "Saloon", "doors": 4, "features": ["Sat nav", "Heated seats"]
    },
    "service_history": "full", "previous_owners": 1, "mot_expiry": "2027-03-01",
    "write_off_category": "none", "outstanding_finance": false, "keys_supplied": 2,
    "show_phone": true, "allow_messages": true, "show_name": true,
    "external_ref": "STOCK-00123",
    "photos": ["https://example.com/photos/front.jpg", "https://example.com/photos/rear.jpg"]
  }'

Field	Notes
category	Slug or id from /vehicle-categories. Required.
heading	Make, model, engine, trim. Required.
description	Plain text, at least 40 words. Links are stripped. Required.
price	GBP, number. Required.
location	UK postcode, town name or a place_id. Required.
condition	new, nearly new, used (default), in parts, damaged.
registration	Optional UK plate. When make and model are missing we fill them from DVLA data.
attributes	Object keyed by attribute slug. Select values are matched by label, case-insensitively. Unknown slugs or options are reported in warnings, never rejected.
Declarations	service_history (full, partial, none, unknown), previous_owners (1 to 5), mot_expiry (YYYY-MM-DD), write_off_category (none, S, N, C, D, unknown), outstanding_finance (bool), keys_supplied (1 to 3), known_faults (text).
Contact	show_phone, allow_messages, show_name. At least one of phone or messages should be on.
external_ref	Your stock id. Used by /ads/sync and the external_ref filter.
photos	Up to 20 public image URLs (JPEG, PNG or WebP, at least 300x200). The first becomes the main photo. Failures are reported in warnings.

Publishing. Adverts from dealer accounts go live immediately unless our screening holds them. Adverts from private accounts are held for review (status: pending_review) and go live once approved.

Photos

Call	What it does
GET/ads/{id}/photos	List photos.
POST/ads/{id}/photos	Add photos: multipart file, or JSON {"url": "..."} / {"urls": [...]}.
DELETE/ads/{id}/photos/{photoId}	Remove a photo. The next one becomes the main photo if needed.

curl -X POST https://www.mobeo.co.uk/api/v1/ads/24136/photos -H "X-API-KEY: $KEY" -F "file=@front.jpg"

Stock sync

POST/ads/sync keeps Mobeo in step with your stock list. Each item is a full advert (same fields as create) with an external_ref. Existing adverts with that reference are updated, new ones are created, and with remove_missing: true any API-sourced advert not in the list is taken offline. Send dry_run: true first to preview.

{
  "dry_run": true,
  "remove_missing": true,
  "ads": [
    {"external_ref": "STOCK-00123", "category": "cars", "heading": "...", "description": "...", "price": 15995, "location": "LS1 4AP", "attributes": {...}, "photos": [...]},
    {"external_ref": "STOCK-00124", ...}
  ]
}

The response lists create, update, remove and errors. Up to 500 items per call.

Errors & limits

HTTP	code	Meaning
401	UNAUTHORIZED	Missing, invalid or revoked key.
403	ACCOUNT_INACTIVE	The account that owns the key is suspended.
404	NOT_FOUND	No such advert, or it belongs to someone else.
422	VALIDATION_ERROR	Field problems; see error.details.
429	RATE_LIMIT_EXCEEDED	300 requests per hour per key, 100 new adverts and 1200 photos per day per account.