MotorSpace API Documentation

Complete reference for the MotorSpace REST API endpoints

Base URL

https://staging.motor-space.co.uk/motorspace

Authentication

Laravel Sanctum (Bearer Token)

Content-Type

application/json

Common Response Format

Field	Type	Description
`status`	string	`success` or `failed`
`message`	string	Human-readable status message
`data`	object	Response payload (when applicable)

HTTP Status Codes

Code	Meaning
200	Success
201	Created
401	Unauthorized / Invalid credentials
403	Forbidden / Account issues
404	Resource not found
409	Conflict (e.g., already verified)
422	Validation error / Invalid data

Authentication

#	Method	Endpoint	Auth	Description
1	POST	`/api/login`	No	Login with email and password
2	POST	`/api/logout`	Yes	Revoke the current Bearer token
3	POST	`/api/forgot-password`	No	Send password reset OTP to email
4	POST	`/api/forgot-password/verify-otp`	No	Verify forgot password OTP
5	POST	`/api/reset-password`	No	Reset password using token

POST 1.1 Login

POST https://staging.motor-space.co.uk/motorspace/api/login

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email`	User's email address
`password`	string	Yes	`string`	User's password

Request Body (JSON)

{
  "email": "",
  "password": ""
}

Success Response (200)

{
  "status": "success",
  "message": "Login successful.",
  "data": {
    "token_type": "Bearer",
    "access_token": "1|abc123...",
    "user": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "status": 1,
      "buy_seller_centric": "buyer",
      "role": "lead_trader"
    }
  }
}

Error Responses

Status	Message
401	Invalid credentials.
403	Your account approval is pending.
403	Your account approval was rejected.
403	Your account is inactive/deleted/suspended/paused.

POST 1.2 Logout

POST https://staging.motor-space.co.uk/motorspace/api/logout

Authentication: Requires a valid Authorization: Bearer <token> header.

Request Parameters

No request body required.

Success Response (200)

{
  "status": "success",
  "message": "Logged out successfully."
}

Error Responses

Status	Message
401	Unauthenticated. (missing or invalid token)

POST 1.3 Forgot Password

POST https://staging.motor-space.co.uk/motorspace/api/forgot-password

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email`	Registered email address

Request Body (JSON)

{
  "email": ""
}

Success Response (200)

{
  "status": "success",
  "message": "Password reset OTP sent successfully.",
  "data": {
    "reset_token": "your-reset-token"
  }
}

Error Responses

Status	Message
404	User not found.
403	Please verify your email address before resetting your password.

Note: A 6-digit OTP and reset link are sent to the email, valid for 10 minutes. The response also includes data.reset_token for API-driven reset flows.

POST 1.4 Verify Forgot Password OTP

POST https://staging.motor-space.co.uk/motorspace/api/forgot-password/verify-otp

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email`	User's email address
`otp`	string	Yes	`digits:6`	6-digit OTP received via email

Request Body (JSON)

{
  "email": "",
  "otp": ""
}

Success Response (200)

{
  "status": "success",
  "message": "OTP verified successfully."
}

Error Responses

Status	Message
404	User not found.
422	Invalid or expired OTP.

POST 1.5 Reset Password

POST https://staging.motor-space.co.uk/motorspace/api/reset-password

Request Parameters

Parameter	Type	Required	Rules	Description
`token`	string	Yes	`string`	Password reset token from email
`email`	string	Yes	`email`	User's email address
`password`	string	Yes	`string, min:8, confirmed`	New password (min 8 chars)
`password_confirmation`	string	Yes	`string`	Must match `password`

Request Body (JSON)

{
  "token": "",
  "email": "",
  "password": "",
  "password_confirmation": ""
}

Success Response (200)

{
  "status": "success",
  "message": "Password reset successfully."
}

Error Responses

Status	Message
422	Invalid token or email.

Signup

#	Method	Endpoint	Auth	Description
1	POST	`/api/signup/about-you`	No	Register a new user account
2	POST	`/api/signup/verify-otp`	No	Verify email OTP during signup
3	POST	`/api/signup/resend-otp`	No	Resend verification OTP
4	POST	`/api/signup/update-info`	No	Update user profile after verification

POST 2.1 Signup - About You

POST https://staging.motor-space.co.uk/motorspace/api/signup/about-you

Request Parameters

Parameter	Type	Required	Rules	Description
`first_name`	string	Yes	`string, max:255`	User's first name
`last_name`	string	Yes	`string, max:255`	User's last name
`business_dealership_name`	string	Yes	`string, max:255`	Business or dealership name
`email`	string	Yes	`email, unique:users`	User's email (must be unique)
`email_confirmation`	string	Yes	`email, same:email`	Must match `email`
`phone`	string	Yes	`string, max:20, unique:users`	Phone number (must be unique)
`password`	string	Yes	`string, min:8, confirmed`	Password (min 8 chars)
`password_confirmation`	string	Yes	`string`	Must match `password`
`mobile_platform`	integer	No	`integer, in:1,2`	1: iOS, 2: Android
`device_token`	string	No	`string`	Push notification device token

Request Body (JSON)

{
  "first_name": "",
  "last_name": "",
  "business_dealership_name": "",
  "email": "",
  "email_confirmation": "",
  "phone": "",
  "password": "",
  "password_confirmation": "",
  "mobile_platform": 1,
  "device_token": ""
}

Success Response (201)

{
  "status": "success",
  "message": "OTP sent to your email",
  "email": "john@example.com"
}

Note: Creates user with lead_trader role and pending approval status. Sends 6-digit OTP valid for 10 minutes.

POST 2.2 Signup - Verify OTP

POST https://staging.motor-space.co.uk/motorspace/api/signup/verify-otp

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email`	User's email address
`otp`	string	Yes	`digits:6`	6-digit OTP received via email

Request Body (JSON)

{
  "email": "",
  "otp": ""
}

Success Response (200)

{
  "status": "success",
  "message": "OTP verified successfully"
}

Error Responses

Status	Message
404	User not found
409	Email is already verified
422	Invalid or expired OTP

POST 2.3 Signup - Resend OTP

POST https://staging.motor-space.co.uk/motorspace/api/signup/resend-otp

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email`	User's email address

Request Body (JSON)

{
  "email": ""
}

Success Response (200)

{
  "status": "success",
  "message": "OTP resent successfully"
}

Error Responses

Status	Message
404	User not found
409	Email is already verified

Note: Invalidates all previous OTPs and sends a new one.

POST 2.4 Signup - Update Info

POST https://staging.motor-space.co.uk/motorspace/api/signup/update-info

Request Parameters

Parameter	Type	Required	Rules	Description
`email`	string	Yes	`email, exists:users`	User's email address
`email_confirmation`	string	Yes	`email, same:email`	Must match `email`
`first_name`	string	Yes	`string, max:255`	User's first name
`last_name`	string	Yes	`string, max:255`	User's last name
`business_dealership_name`	string	Yes	`string, max:255`	Business or dealership name
`phone`	string	Yes	`string, max:20, unique`	Phone number (unique per user)
`password`	string	No	`string, min:8, confirmed`	New password (optional)
`password_confirmation`	string	No	`string`	Required if `password` is provided
`about_user_and_business`	string	No	`string`	Bio / business description
`mobile_platform`	integer	No	`integer, in:1,2`	1: iOS, 2: Android
`device_token`	string	No	`string`	Push notification device token

Request Body (JSON)

{
  "email": "",
  "email_confirmation": "",
  "first_name": "",
  "last_name": "",
  "business_dealership_name": "",
  "phone": "",
  "password": "",
  "password_confirmation": "",
  "about_user_and_business": "",
  "mobile_platform": 1,
  "device_token": ""
}

Success Response (200)

{
  "status": "success",
  "message": "Profile updated successfully"
}

Error Responses

Status	Message
404	User not found
403	Please verify your email before updating profile

Note: Email must be verified before profile can be updated.

Terms & Conditions

#	Method	Endpoint	Auth	Description
1	POST	`/api/accept-terms`	No	Accept terms and conditions

POST 3.1 Accept Terms

POST https://staging.motor-space.co.uk/motorspace/api/accept-terms

Request Parameters

Parameter	Type	Required	Rules	Description
`user_id`	integer	Yes	`integer, exists:users`	User's ID
`type`	string	No	`string, in:sign_up_terms`	Terms type (default: `sign_up_terms`)

Request Body (JSON)

{
  "user_id": 1,
  "type": "sign_up_terms"
}

Success Response (200)

{
  "status": "success",
  "message": "Terms accepted successfully"
}

User

#	Method	Endpoint	Auth	Description
1	GET	`/api/user`	Yes	Get authenticated user profile
2	PUT	`/api/profile`	Yes	Update authenticated user profile

GET 4.1 Get Current User

GET https://staging.motor-space.co.uk/motorspace/api/user

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "business_dealership_name": "Doe Motors",
  "email": "john@example.com",
  "phone": "+1234567890",
  "about_user_and_business": "Premium car dealership",
  "profile_picture": null,
  "status": 1,
  "email_verified_at": "2026-03-31T12:00:00.000000Z",
  "created_at": "2026-03-31T10:00:00.000000Z",
  "updated_at": "2026-03-31T12:00:00.000000Z"
}

Error Responses

Status	Message
401	Unauthenticated

PUT 4.2 Update Profile

PUT https://staging.motor-space.co.uk/motorspace/api/profile

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes

Request Body

Field	Type	Required	Description
`first_name`	string	No	User's first name (max 255)
`last_name`	string	No	User's last name (max 255)
`phone_number`	string	No	Phone number (max 20, must be unique)
`current_password`	string	Required when changing password	User's current password — must match before any password change is applied
`new_password`	string	Required with current_password	New password (min 8 characters)
`confirm_password`	string	Required with new_password	Must match new_password

Success Response (200)

{
  "status": "success",
  "message": "Profile updated successfully.",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+447000000001"
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated
422	`Current password is incorrect.` — when the provided current_password does not match
422	Validation errors (e.g. phone_number already taken, confirm_password mismatch)

Register Vehicle

Authentication Required: All Register Vehicle endpoints require a valid Sanctum Bearer token. Use Content-Type: multipart/form-data for endpoints that accept file uploads.

#	Method	Endpoint	Auth	Description
1	GET	`/api/register-vehicle/reference-data`	Yes	Get reference data (body types, fuel types, etc.)
2	POST	`/api/register-vehicle/lookup`	Yes	Lookup vehicle by registration number
3	POST	`/api/register-vehicle/confirm-derivative`	Yes	Confirm vehicle derivative selection
4	GET	`/api/register-vehicle/listings`	Yes	List all vehicle listings
5	POST	`/api/register-vehicle/listings`	Yes	Create a new vehicle listing
6	GET	`/api/register-vehicle/listings/{listing}`	Yes	Get a specific vehicle listing
6a	GET	`/api/register-vehicle/listings/{listing}/edit`	Yes	Get listing data pre-populated for editing
6b	PUT	`/api/register-vehicle/listings/{listing}`	Yes	Update an existing vehicle listing
6c	DELETE	`/api/register-vehicle/listings/{listing}`	Yes	Delete a vehicle listing (draft/sold/withdrawn/expired only)
6d	GET	`/api/register-vehicle/listings/{listing}/confirm-details`	Yes	Get full vehicle details for the confirm/review step
7	GET	`/api/register-vehicle/listings/{listing}/exterior-damages`	Yes	List all exterior damages for a listing
8	POST	`/api/register-vehicle/listings/{listing}/exterior-damages`	Yes	Add/update exterior damage report
9	DELETE	`/api/register-vehicle/listings/{listing}/exterior-damages/{damage}`	Yes	Delete an exterior damage entry
10	GET	`/api/register-vehicle/listings/{listing}/interior-damages`	Yes	List all interior damages for a listing
11	POST	`/api/register-vehicle/listings/{listing}/interior-damages`	Yes	Add/update interior damage report
12	DELETE	`/api/register-vehicle/listings/{listing}/interior-damages/{damage}`	Yes	Delete an interior damage entry
13	PUT	`/api/register-vehicle/listings/{listing}/tyre-report`	Yes	Save tyre condition report
13a	GET	`/api/register-vehicle/listings/{listing}/tyre-report`	Yes	Get tyre condition report by listing ID
14	PUT	`/api/register-vehicle/listings/{listing}/mechanical-report`	Yes	Save mechanical condition report
14a	GET	`/api/register-vehicle/listings/{listing}/mechanical-report`	Yes	Get mechanical condition report by listing ID
15	POST	`/api/register-vehicle/listings/{listing}/additional-info`	Yes	Add additional information and photos
15a	GET	`/api/register-vehicle/listings/{listing}/additional-info`	Yes	Get additional information and photos by listing ID
16	PUT	`/api/register-vehicle/listings/{listing}/pricing`	Yes	Set listing price

GET 5.1 Reference Data

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/reference-data

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Register vehicle reference data loaded.",
  "data": {
    "options": {
      "vehicle_types": ["car", "lcv"],
      "vehicle_statuses": ["physical", "dealt_and_due_in", "underwrite"],
      "transmissions": ["manual", "automatic"],
      "timescales": ["2-7 days", "8-14 days", "14-28 days"],
      "v5_available": ["yes", "no", "number_only"],
      "v5_pages": [1, 2, 3],
      "keys": [1, 2, 3, 4],
      "vat_type_car": ["vat_marginal", "vat_qualifying"],
      "vat_type_lcv": ["plus_vat", "no_vat"]
    },
    "fuel_types": [{ "id": 1, "name": "Diesel" }, ...],
    "body_types": [{ "id": 1, "name": "Saloon" }, ...],
    "branches": [{ "id": 1, "name": "Main Branch", "slug": "main-branch", "address": "...", "postcode": "...", "is_active": true }, ...],
    "business_locations": [...]
  }
}

POST 5.2 Vehicle Lookup

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/lookup

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

Parameter	Type	Required	Rules	Description
`vrm`	string	Yes	`string, max:10`	Vehicle registration mark
`mileage`	integer	Yes	`integer, min:0`	Current vehicle mileage

Request Body (JSON)

{
  "vrm": "AB12CDE",
  "mileage": 45000
}

Success Response (200) — Single Derivative

{
  "status": "success",
  "message": "Vehicle lookup completed successfully.",
  "data": {
    "lookup_id": 42,
    "cached": false,
    "has_alternative_derivatives": false,
    "data": {
      "make": "BMW",
      "model": "3 Series",
      "vehicle_variant": "320d M Sport",
      "cap_clean_price": 18500,
      ...
    }
  }
}

Success Response (200) — Multiple Derivatives

{
  "status": "success",
  "message": "Alternative derivatives found for the registration.",
  "data": {
    "lookup_id": 42,
    "cached": false,
    "has_alternative_derivatives": true,
    "audit_id": "abc123",
    "derivatives": [
      { "cap_id": 12345, "name": "320d M Sport", ... }
    ],
    "vehicle_preview": {
      "make": "BMW",
      "colour": "Black",
      "fuel_type": "Diesel",
      "year_of_manufacture": 2020,
      "mot_status": "Valid",
      "mot_expiry_date": "2026-06-15",
      "tax_status": "Taxed",
      "engine_capacity": 1995,
      "co2_emissions": 120
    }
  }
}

Note: When has_alternative_derivatives is true, the user must select a derivative and call the Confirm Derivative endpoint with the chosen cap_id.

Error Responses

Status	Message
422	Vehicle lookup failed (invalid VRM or external service error)

POST 5.3 Confirm Derivative

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/confirm-derivative

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

Parameter	Type	Required	Rules	Description
`vrm`	string	Yes	`string, max:10`	Vehicle registration mark
`mileage`	integer	Yes	`integer, min:0`	Current vehicle mileage
`cap_id`	integer	Yes	`integer`	CAP derivative ID from lookup

Request Body (JSON)

{
  "vrm": "AB12CDE",
  "mileage": 45000,
  "cap_id": 12345
}

Success Response (200)

{
  "status": "success",
  "message": "Vehicle derivative confirmed successfully.",
  "data": {
    "vrm": "AB12CDE",
    "cap_id": 12345,
    "derivative_details": {...}
  }
}

Error Responses

Status	Message
422	Derivative confirmation failed

GET 5.4 List Vehicle Listings

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listings loaded successfully.",
  "data": {
    "counts": {
      "all": 5,
      "draft": 2,
      "pending_review": 1,
      "active": 1,
      "sold": 1,
      "withdrawn": 0,
      "expired": 0
    },
    "listings": [
      {
        "id": 1,
        "uuid": "a1b2c3d4-...",
        "registration_plate": "AB12CDE",
        "formatted_registration_plate": "AB12 CDE",
        "title": "BMW 3 Series 320d M Sport",
        "vehicle_variant": "320d M Sport",
        "vehicle_type": "car",
        "fuel_type": "Diesel",
        "body_type": "Saloon",
        "colour": "Black",
        "mileage": 45000,
        "listing_price": 15000,
        "status": "draft",
        "price_above_guideline": false,
        "primary_photo": null,
        "steps": {...},
        "submitted_at": null,
        "updated_at": "2026-04-07T10:00:00.000Z"
      }
    ]
  }
}

POST 5.5 Create Vehicle Listing

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters (Always Required)

Parameter	Type	Required	Rules	Description
`registration_plate`	string	Yes	`string, max:10`	Vehicle registration plate
`make`	string	Yes	`string, max:255`	Vehicle make
`model`	string	Yes	`string, max:255`	Vehicle model
`vehicle_variant`	string	Yes	`string, max:255`	Vehicle variant/derivative
`vehicle_type`	string	Yes	`in:car,lcv`	Vehicle type
`vehicle_colour`	string	Yes	`string, max:100`	Vehicle colour
`transmission`	string	Yes	`in:manual,automatic`	Transmission type
`fuel_type`	string	Yes	`string, max:50, exists:fuel_types`	Fuel type name
`body_type`	string	Yes	`string, max:50, exists:body_types`	Body type name
`engine_size`	numeric	Yes	`numeric`	Engine size (e.g. 2.0)
`mileage`	integer	Yes	`integer, min:0`	Current mileage
`status`	string	No	`in:draft,submit`	Save as draft or submit

Request Parameters (Required if status = submit, nullable if draft)

Parameter	Type	Rules	Description
`mileage_warranted`	boolean	`boolean`	Is mileage warranted
`number_of_services`	integer	`integer, min:0`	Number of services
`last_service_date`	date	`date`	Date of last service
`keys`	integer	`integer, in:1,2,3,4`	Number of keys
`previous_owners`	integer	`integer, min:0`	Number of previous owners
`last_registration_date`	string	`string, max:50`	Last registration date
`vehicle_status`	string	`in:physical,dealt_and_due_in,underwrite`	Vehicle status
`is_private_plate`	boolean	`boolean`	Has private plate
`v5_available`	string	`in:yes,no,number_only,v5_number_only`	V5 document availability
`showing_finance`	boolean	`boolean`	Is showing finance
`hpi_clear`	boolean	`boolean`	Is HPI clear
`is_ex_taxi`	boolean	`boolean`	Is ex-taxi
`is_import`	boolean	`boolean`	Is an import
`is_modified`	boolean	`boolean`	Has modifications
`business_location_id`	integer	`exists:business_locations`	Business location (must belong to user)

Conditional Parameters

Parameter	Type	Condition	Rules	Description
`timescale`	string	vehicle_status = dealt_and_due_in or underwrite	`in:2-7 days,8-14 days,14-28 days`	Expected timescale
`v5_pages`	integer	v5_available = yes	`integer, in:1,2,3`	Number of V5 pages
`private_plate_staying`	boolean	is_private_plate = true	`boolean`	Is private plate staying on vehicle
`modification_description`	string	is_modified = true	`string`	Description of modifications
`vat_type_car`	string	vehicle_type = car	`in:vat_marginal,vat_qualifying`	VAT type for cars
`vat_type_lcv`	string	vehicle_type = lcv	`in:plus_vat,no_vat`	VAT type for LCVs

Optional Parameters

Parameter	Type	Rules	Description
`registration_plate_number`	string	`string, max:10`	Registration plate number
`lookup_id`	integer	`integer, exists:vehicle_lookups`	ID from a prior vehicle lookup
`api_data_modified`	boolean	`boolean`	Whether API lookup data was modified
`branch_id`	integer	`exists:branches`	Branch ID
`original_registration_plate`	string	`string, max:15`	Original registration plate (if changed)

Request Body (JSON) — Minimum for Draft

{
  "registration_plate": "AB12CDE",
  "make": "BMW",
  "model": "3 Series",
  "vehicle_variant": "320d M Sport",
  "vehicle_type": "car",
  "vehicle_colour": "Black",
  "transmission": "automatic",
  "fuel_type": "Diesel",
  "body_type": "Saloon",
  "engine_size": 2.0,
  "mileage": 45000,
  "status": "draft"
}

Success Response (201)

{
  "status": "success",
  "message": "Vehicle information saved. Continue with the damage report.",
  "data": {
    "listing": {
      "id": 1,
      "uuid": "a1b2c3d4-...",
      "registration_plate": "AB12CDE",
      "formatted_registration_plate": "AB12 CDE",
      "make": { "id": 1, "name": "BMW" },
      "model": { "id": 1, "name": "3 Series" },
      ... // Full listing object (see 5.6 Show Listing)
    },
    "next_step": "report_exterior_damage"
  }
}

Note: When status is "draft", the message is "Vehicle listing saved as draft." and next_step is "draft_saved".

GET 5.6 Show Vehicle Listing

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listing loaded successfully.",
  "data": {
    "listing": {
      "id": 1,
      "uuid": "a1b2c3d4-...",
      "registration_plate": "AB12CDE",
      "formatted_registration_plate": "AB12 CDE",
      "registration_plate_number": null,
      "original_registration_plate": null,
      "make": { "id": 1, "name": "BMW" },
      "model": { "id": 1, "name": "3 Series" },
      "vehicle_variant": { "id": 1, "name": "320d M Sport" },
      "vehicle_type": "car",
      "vehicle_colour": { "id": 1, "name": "Black" },
      "transmission": "automatic",
      "fuel_type": { "id": 1, "name": "Diesel" },
      "body_type": { "id": 1, "name": "Saloon" },
      "engine_size": 2.0,
      "mileage": 45000,
      "mileage_warranted": true,
      "number_of_services": 5,
      "last_service_date": "2025-12-01",
      "keys": 2,
      "previous_owners": 1,
      "last_registration_date": "2020-06-15",
      "vehicle_status": "physical",
      "timescale": null,
      "is_private_plate": false,
      "private_plate_staying": null,
      "v5_available": "yes",
      "v5_pages": 2,
      "showing_finance": false,
      "hpi_clear": true,
      "is_ex_taxi": false,
      "is_import": false,
      "is_modified": false,
      "modification_description": null,
      "vat_type_car": "vat_marginal",
      "vat_type_lcv": null,
      "has_mechanical_issues": false,
      "mechanical_issues_description": null,
      "additional_information": null,
      "business_location": null,
      "branch": { "id": 1, "name": "Main", "slug": "main" },
      "tyre_report": {
        "all_over_3mm": true,
        "ns_front_mm": null,
        "os_front_mm": null,
        "ns_rear_mm": null,
        "os_rear_mm": null,
        "confirmed_accurate": null
      },
      "exterior_damages": [
        { "id": 1, "location_key": "front_bumper", "location_title": "Front Bumper", "description": "Scratch", "photos": [...] }
      ],
      "interior_damages": [
        { "id": 1, "location_title": "Dashboard", "description": "Crack", "photos": [...] }
      ],
      "additional_photos": [],
      "pricing": {
        "cap_valuation_clean": 18500,
        "cap_valuation_clean_date": "2026-04-07",
        "listing_price": 15000,
        "price_above_guideline": false,
        "terms_accepted": true,
        "context": {
          "vehicle_title": "BMW 3 Series",
          "vehicle_variant": "320d M Sport",
          "vehicle_reg_plate": "AB12CDE",
          "formatted_vehicle_reg_plate": "AB12 CDE",
          "cap_clean_price": 18500,
          "cap_valuation_date": "2026-04-07",
          "guideline_min_price": 14800,
          "guideline_max_price": 19425
        }
      },
      "lookup": null,
      "status": "draft",
      "completion_step": 3,
      "steps": {...},
      "submitted_at": null,
      "created_at": "2026-04-07T10:00:00.000Z",
      "updated_at": "2026-04-07T10:00:00.000Z"
    }
  }
}

GET 5.6a Edit Vehicle Listing

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/edit

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listing loaded for editing.",
  "data": {
    "listing": { /* same shape as Show Listing response */ }
  }
}

PUT 5.6b Update Vehicle Listing

PUT https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}

Note: Only fields included in the request body will be updated. Omitted fields retain their existing values.

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Request Parameters (all optional)

Parameter	Type	Required	Notes
`registration_plate`	string	No	Max 10 chars. Must not conflict with another active listing.
`make`	string	No
`model`	string	No	Send with `make` when updating model.
`vehicle_variant`	string	No	Send with `make` and `model`.
`vehicle_type`	string	No	`car`, `lcv`, `van`, `motorcycle`, `other`
`vehicle_colour`	string	No
`transmission`	string	No	`manual`, `automatic`
`fuel_type`	string	No	Must exist in fuel_types table
`body_type`	string	No	Must exist in body_types table
`engine_size`	numeric	No
`mileage`	integer	No	Min 0
`mileage_warranted`	boolean	Conditional*
`number_of_services`	integer	Conditional*	Min 0
`last_service_date`	date	No
`keys`	integer	Conditional*	`1`, `2`, `3`, `4`
`previous_owners`	integer	Conditional*	Min 0
`last_registration_date`	string	Conditional*
`vehicle_status`	string	Conditional*	`physical`, `dealt_and_due_in`, `underwrite`
`timescale`	string	No	Required if `vehicle_status` is `dealt_and_due_in` or `underwrite` when submitting
`is_private_plate`	boolean	Conditional*
`private_plate_staying`	boolean	No	Required if `is_private_plate` is true when submitting
`original_registration_plate`	string	No
`registration_plate_number`	string	No
`v5_available`	string	Conditional*	`yes`, `no`, `number_only`
`v5_pages`	integer	No	Required if `v5_available` is `yes` when submitting. Values: `1`, `2`, `3`
`showing_finance`	boolean	Conditional*
`hpi_clear`	boolean	Conditional*
`is_ex_taxi`	boolean	Conditional*
`is_import`	boolean	Conditional*
`is_modified`	boolean	Conditional*
`modification_description`	string	No	Required if `is_modified` is true when submitting
`vat_type_car`	string	No	Required if `vehicle_type` is `car` when submitting. Values: `vat_marginal`, `vat_qualifying`
`vat_type_lcv`	string	No	Required if `vehicle_type` is `lcv` when submitting. Values: `plus_vat`, `no_vat`
`branch_id`	integer	No	Must exist in branches table
`business_location_id`	integer	Conditional*	Must belong to authenticated user
`status`	string	No	`draft` or `submit`. When `submit`, conditional fields become required.

* Conditional — required when status=submit, otherwise nullable.

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listing updated.",
  "data": {
    "listing": { /* same shape as Show Listing response */ }
  }
}

DELETE 5.6c Delete Vehicle Listing

DELETE https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}

Note: Only listings with a status of draft, sold, withdrawn, or expired can be deleted. Attempting to delete an active or pending_review listing will return a 422 error. Deletion is soft — the record is retained in the database.

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listing deleted successfully."
}

Error Responses

Status	Description
401	Unauthenticated — missing or invalid token.
403	The listing does not belong to the authenticated user.
404	Listing not found.
422	Active or pending listings cannot be deleted.

GET 5.6d Confirm All Vehicle Details

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/confirm-details

Use this endpoint for the review/confirm step of the vehicle registration flow — after all condition data has been entered and before pricing. Returns the full vehicle record including all form values, exterior damages, interior damages, tyre health, mechanical health, and additional information.

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Vehicle details loaded for confirmation.",
  "data": {
    "listing": {
      "id": 1,
      "registration_plate": "AB12CDE",
      "formatted_registration_plate": "AB12 CDE",
      "make": { "id": 1, "name": "BMW" },
      "model": { "id": 1, "name": "3 Series" },
      "vehicle_variant": { "id": 1, "name": "320d M Sport" },
      "vehicle_type": "car",
      "vehicle_colour": { "id": 1, "name": "Black" },
      "transmission": "automatic",
      "fuel_type": { "id": 1, "name": "Diesel" },
      "body_type": { "id": 1, "name": "Saloon" },
      "engine_size": 2.0,
      "mileage": 45000,
      "mileage_warranted": true,
      "number_of_services": 4,
      "last_service_date": "2025-06-01",
      "keys": 2,
      "previous_owners": 1,
      "last_registration_date": "2020-06-15",
      "vehicle_status": "physical",
      "timescale": null,
      "is_private_plate": false,
      "v5_available": "yes",
      "v5_pages": 2,
      "showing_finance": false,
      "hpi_clear": true,
      "is_ex_taxi": false,
      "is_import": false,
      "is_modified": false,
      "modification_description": null,
      "vat_type_car": "vat_marginal",
      "vat_type_lcv": null,
      "has_mechanical_issues": true,
      "mechanical_issues_description": "Engine warning light active.",
      "additional_information": "Full service history.",
      "exterior_damages": [
        {
          "id": 1,
          "location_key": "front_bumper",
          "location_label": "Front Bumper",
          "description": "Scratch on lower section.",
          "sort_order": 1,
          "photos": [{ "id": 1, "url": "https://...", "filename": "damage_1.jpg" }]
        }
      ],
      "interior_damages": [
        {
          "id": 2,
          "location_label": "Dashboard",
          "description": "Crack near air vent.",
          "sort_order": 1,
          "photos": []
        }
      ],
      "tyre_report": {
        "id": 1,
        "all_over_3mm": false,
        "ns_front_mm": 2.5,
        "os_front_mm": 3.1,
        "ns_rear_mm": 3.2,
        "os_rear_mm": 3.0,
        "confirmed_accurate": true,
        "has_low_tread": true,
        "tread_summary": {
          "ns_front": { "mm": 2.5, "ok": false },
          "os_front": { "mm": 3.1, "ok": true },
          "ns_rear": { "mm": 3.2, "ok": true },
          "os_rear": { "mm": 3.0, "ok": true }
        }
      },
      "additional_photos": [],
      "steps": {
        "vehicle_information_saved": true,
        "has_exterior_damages": true,
        "has_interior_damages": true,
        "has_tyre_report": true,
        "mechanical_report_saved": true,
        "additional_info_saved": true,
        "pricing_saved": false
      },
      "status": "draft",
      "completion_step": 5
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Listing does not belong to the authenticated user
404	Listing not found

GET 5.7 List Exterior Damages

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/exterior-damages

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Exterior damages loaded successfully.",
  "data": {
    "listing_id": 12,
    "listing_uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
    "exterior_damages": [
      {
        "id": 5,
        "location_key": "front_bumper",
        "location_label": "Front bumper",
        "description": "Scuff on lower edge.",
        "sort_order": 1,
        "photos": [{ ... }]
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Listing does not belong to the authenticated user
404	Listing not found

POST 5.8 Store Exterior Damage

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/exterior-damages

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`multipart/form-data`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Request Parameters

Parameter	Type	Required	Rules	Description
`damage_id`	integer	No	`integer`	Existing damage ID (for update)
`location_key`	string	Yes	`string, max:100`	Damage location key identifier
`location_label`	string	Yes	`string, max:255`	Human-readable location label
`description`	string	Yes	`string`	Damage description
`photos[]`	file	Yes*	`image, mimes:jpg,jpeg,png,webp, max:10240`	Damage photos (1-3). *Nullable when updating.

Success Response (201 / 200)

{
  "status": "success",
  "message": "Exterior damage saved successfully.",
  "data": {
    "listing": { ... },
    "saved_damage_id": 5
  }
}

Note: Returns 201 for new entries and 200 for updates. Each photo must be max 10MB. Pass damage_id to update an existing damage entry.

DELETE 5.9 Delete Exterior Damage

DELETE https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/exterior-damages/{damage}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID
`damage`	integer	Exterior damage ID

Success Response (200)

{
  "status": "success",
  "message": "Exterior damage deleted successfully.",
  "data": {
    "listing": { ... }
  }
}

GET 5.10 List Interior Damages

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/interior-damages

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200)

{
  "status": "success",
  "message": "Interior damages loaded successfully.",
  "data": {
    "listing_id": 12,
    "listing_uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
    "interior_damages": [
      {
        "id": 3,
        "location_label": "Passenger seat",
        "description": "Small tear in fabric.",
        "sort_order": 1,
        "photos": [{ ... }]
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Listing does not belong to the authenticated user
404	Listing not found

POST 5.11 Store Interior Damage

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/interior-damages

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`multipart/form-data`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Request Parameters

Parameter	Type	Required	Rules	Description
`damage_id`	integer	No	`integer`	Existing damage ID (for update)
`location_label`	string	Yes	`string, max:150`	Interior damage location label
`description`	string	Yes	`string`	Damage description
`photos[]`	file	Yes*	`image, mimes:jpg,jpeg,png,webp, max:10240`	Damage photos (1-3). *Nullable when updating.

Success Response (201 / 200)

{
  "status": "success",
  "message": "Interior damage saved successfully.",
  "data": {
    "listing": { ... },
    "saved_damage_id": 3
  }
}

Note: Unlike exterior damages, interior damages do not require a location_key field.

DELETE 5.12 Delete Interior Damage

DELETE https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/interior-damages/{damage}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID
`damage`	integer	Interior damage ID

Success Response (200)

{
  "status": "success",
  "message": "Interior damage deleted successfully.",
  "data": {
    "listing": { ... }
  }
}

PUT 5.13 Tyre Report

PUT https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/tyre-report

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/tyre-report

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200) - Get Tyre Report

{
  "status": "success",
  "message": "Tyre report loaded successfully.",
  "data": {
    "listing_id": 123,
    "listing_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "tyre_report": {
      "all_over_3mm": false,
      "ns_front_mm": 2.7,
      "os_front_mm": 3.2,
      "ns_rear_mm": 3.4,
      "os_rear_mm": 3.1,
      "confirmed_accurate": true,
      "has_low_tread": true,
      "tread_summary": "2.7 / 3.2 / 3.4 / 3.1"
    }
  }
}

Request Parameters

Parameter	Type	Required	Rules	Description
`all_over_3mm`	boolean	Yes	`boolean`	Are all tyres over 3mm tread?
`ns_front_mm`	numeric	Conditional	`numeric, between:0,99.9`	Near-side front tread (mm). Required if all_over_3mm = false.
`os_front_mm`	numeric	Conditional	`numeric, between:0,99.9`	Off-side front tread (mm). Required if all_over_3mm = false.
`ns_rear_mm`	numeric	Conditional	`numeric, between:0,99.9`	Near-side rear tread (mm). Required if all_over_3mm = false.
`os_rear_mm`	numeric	Conditional	`numeric, between:0,99.9`	Off-side rear tread (mm). Required if all_over_3mm = false.
`confirmed_accurate`	boolean	No	`boolean`	User confirms data accuracy

Request Body (JSON) — All over 3mm

{
  "all_over_3mm": true
}

Request Body (JSON) — Individual measurements

{
  "all_over_3mm": false,
  "ns_front_mm": 4.5,
  "os_front_mm": 5.0,
  "ns_rear_mm": 3.2,
  "os_rear_mm": 2.8
}

Success Response (200)

{
  "status": "success",
  "message": "Tyre report saved successfully.",
  "data": {
    "listing": { ... },
    "next_step": "mechanical_report"
  }
}

PUT 5.14 Mechanical Report

PUT https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/mechanical-report

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/mechanical-report

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200) - Get Mechanical Report

{
  "status": "success",
  "message": "Mechanical report loaded successfully.",
  "data": {
    "listing_id": 123,
    "listing_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "has_mechanical_issues": true,
    "mechanical_issues_description": "Intermittent warning light."
  }
}

Request Parameters

Parameter	Type	Required	Rules	Description
`has_mechanical_issues`	boolean	Yes	`boolean`	Does the vehicle have mechanical issues?
`mechanical_issues_description`	string	Conditional	`string, max:5000`	Description of issues. Required if has_mechanical_issues = true.

Request Body (JSON)

{
  "has_mechanical_issues": true,
  "mechanical_issues_description": "Minor engine noise at idle"
}

Success Response (200)

{
  "status": "success",
  "message": "Mechanical report saved successfully.",
  "data": {
    "listing": { ... },
    "next_step": "additional_info"
  }
}

POST 5.15 Additional Information

POST https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/additional-info

GET https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/additional-info

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`multipart/form-data`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Success Response (200) - Get Additional Info

{
  "status": "success",
  "message": "Additional info loaded successfully.",
  "data": {
    "listing_id": 123,
    "listing_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "additional_information": "Rear camera fitted.",
    "additional_photos": [
      {
        "id": 901,
        "uuid": "adf2f133-5e2d-4925-b2ad-b1e9f46f9e31",
        "filename": "vehicle_photo_123.jpg",
        "collection": "vehicle_photo",
        "type_of_media": "additional-media",
        "url": "https://staging.motor-space.co.uk/motorspace/storage/vehicle-photos/123/vehicle_photo_123.jpg"
      }
    ]
  }
}

Request Parameters

Parameter	Type	Required	Rules	Description
`additional_information`	string	No	`string, max:5000`	Additional notes about the vehicle
`photos[]`	file	No	`image, mimes:jpg,jpeg,png,webp, max:10240`	Additional photos (max 3, each max 10MB)

Success Response (200)

{
  "status": "success",
  "message": "Additional information saved successfully.",
  "data": {
    "listing": { ... },
    "next_step": "verify_vehicle_information"
  }
}

PUT 5.16 Set Listing Price

PUT https://staging.motor-space.co.uk/motorspace/api/register-vehicle/listings/{listing}/pricing

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing`	integer	Vehicle listing ID

Request Parameters

Parameter	Type	Required	Rules	Description
`listing_price`	string	Yes	`string, max:20`	Formatted listing price (e.g. "15,000")
`listing_price_numeric`	numeric	Yes	`numeric, min:1, max:999999999`	Numeric price value
`agree_terms`	boolean	No	`boolean`	Agree to listing terms

Request Body (JSON)

{
  "listing_price": "15,000",
  "listing_price_numeric": 15000,
  "agree_terms": true
}

Success Response (200)

{
  "status": "success",
  "message": "Listing price saved successfully.",
  "data": {
    "listing": { ... },
    "next_step": "list_of_vehicles_for_sale"
  }
}

Marketplace

Authentication Required: Marketplace endpoints require a valid Sanctum Bearer token.

#	Method	Endpoint	Auth	Description
1	GET	`/api/marketplace/listings`	Yes	List all active vehicles from other users
2	GET	`/api/marketplace/listings/{uuid}`	Yes	Get detailed information for a specific vehicle
3	POST	`/api/marketplace/listings/{uuid}/offers`	Yes	Send offer for a marketplace vehicle
4	PATCH	`/api/marketplace/listings/{listing_uuid}/offers/{offer_uuid}`	Yes	Edit an existing pending offer for that marketplace vehicle
5	POST	`/api/marketplace/listings/{uuid}/buy-now`	Yes	Purchase a marketplace vehicle directly at the listed price
6	GET	`/api/offer-received/listings/{uuid}`	Yes	Get seller-owned offer received listing detail with highest incoming offer

GET 6.1 List Marketplace Vehicles

GET https://staging.motor-space.co.uk/motorspace/api/marketplace/listings

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Marketplace listings loaded successfully.",
  "data": {
    "total": 1,
    "listings": [
      {
        "id": 42,
        "uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
        "registration_plate": "BB22BBB",
        "formatted_registration_plate": "BB22 BBB",
        "title": "Bmw 7 Series",
        "vehicle_variant": "730d xDrive M Sport 4dr Auto",
        "vehicle_status": "physical",
        "vehicle_status_label": "Physical",
        "mileage": 50000,
        "number_of_services": 5,
        "previous_owners": 2,
        "transmission": "automatic",
        "fuel_type": "Diesel",
        "colour": "Grey",
        "is_ex_taxi": false,
        "is_import": false,
        "showing_finance": false,
        "is_modified": false,
        "has_mechanical_issues": false,
        "v5_available": "yes",
        "hpi_clear": true,
        "cap_valuation_clean": 18950,
        "listing_price": 19500,
        "last_registration_date": "2022-06-15",
        "tyre_report": {
          "all_over_3mm": true
        },
        "has_condition_report": true,
        "exterior_damages_count": 1,
        "interior_damages_count": 0,
        "business_location": {
          "id": 3,
          "location_name": "Main Site",
          "town_city": "Leicester"
        },
        "submitted_at": "2026-04-16T09:00:00.000000Z"
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated

Note: Your own active listings are intentionally excluded from this marketplace response.

GET 6.2 Get Marketplace Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/marketplace/listings/{uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Marketplace listing details loaded successfully.",
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "BMW 3 Series",
    "photos": [
      { "url": "..." }
    ],
    "exterior_damages": [],
    "interior_damages": [],
    "tyre_report": { ... },
    "mechanical_issues": { ... },
    "additional_information": "..."
  }
}

Error Responses

Status	Message
404	Not Found (if inactive or owned by requester)

POST 6.3 Send Marketplace Offer

POST https://staging.motor-space.co.uk/motorspace/api/marketplace/listings/{uuid}/offers

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body

Field	Type	Required	Validation
`offer_amount`	string	Yes	Must be numeric, less than listing price, and no less than 90% of listing price
`vehicle_location_id`	integer	Yes	Must exist in business_locations and belong to authenticated user
`agree_terms`	boolean	Yes	Must be accepted
`message`	string	No	Optional, max 1000 chars

Success Response (201)

{
  "status": "success",
  "message": "Offer sent successfully.",
  "data": {
    "id": 101,
    "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
    "offer_thread_id": 18,
    "offer_type": "first_offer",
    "direction": "buyer_to_seller",
    "amount_minor": 1200000,
    "currency": "GBP",
    "approval_status": "not_required",
    "visibility_status": "live",
    "decision_status": "pending"
  }
}

Error Responses

Status	Message
401	Unauthenticated
404	Listing not found / inaccessible
422	Validation failed (invalid threshold/location/terms)

PATCH 6.4 Edit Marketplace Offer

PATCH https://staging.motor-space.co.uk/motorspace/api/marketplace/listings/{listing_uuid}/offers/{offer_uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body

Field	Type	Required	Validation
`offer_amount`	string	Yes	Must be numeric, less than listing price, and no less than 90% of listing price
`vehicle_location_id`	integer	Yes	Must exist in business_locations and belong to authenticated user
`agree_terms`	boolean	Yes	Must be accepted
`message`	string	No	Optional, max 1000 chars

Success Response (200)

{
  "status": "success",
  "message": "Offer updated successfully.",
  "data": {
    "id": 101,
    "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
    "offer_thread_id": 18,
    "offer_type": "first_offer",
    "direction": "buyer_to_seller",
    "amount_minor": 1180000,
    "currency": "GBP",
    "approval_status": "not_required",
    "visibility_status": "live",
    "decision_status": "pending"
  }
}

Error Responses

Status	Message
401	Unauthenticated
404	Listing or offer not found / inaccessible
422	Validation failed (invalid threshold/location/terms or non-editable offer)

POST 6.5 Buy Now Marketplace Listing

POST https://staging.motor-space.co.uk/motorspace/api/marketplace/listings/{uuid}/buy-now

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body

Field	Type	Required	Validation
`vehicle_location_id`	integer	Yes	Must exist in business_locations and belong to authenticated user
`agree_terms`	boolean	Yes	Must be accepted

Success Response (201)

{
  "status": "success",
  "message": "Vehicle purchased successfully.",
  "data": {
    "uuid": "4d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
    "listing_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

Error Responses

Status	Message
401	Unauthenticated
404	Listing not found / inaccessible
422	Validation failed (invalid location, terms not accepted, or listing not active)

GET 7.5 Counter Recevied Detail View

GET https://staging.motor-space.co.uk/motorspace/api/counter-received/listings/{uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Counter received listing details loaded successfully.",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "registration_plate": "AB12CDE",
    "formatted_registration_plate": "AB12 CDE",
    "title": "Volkswagen T-Roc",
    "listing_price": 18500,
    "counter_offers_received": {
      "count": 1,
      "response_window": {
        "time_limit_minutes": 240,
        "working_hours_start": "09:00",
        "working_hours_end": "17:00"
      },
      "items": [
        {
          "id": 201,
          "uuid": "2e8bb8fd-8b5d-4dd6-8c28-0b53e12ee3f1",
          "amount_minor": 1870000,
          "currency": "GBP",
          "remaining_time": "3h 30m",
          "parent_offer": {
            "id": 200,
            "amount_minor": 1840000,
            "currency": "GBP"
          }
        }
      ]
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Forbidden (listing owner cannot access this endpoint)
404	No pending counter offers found for this listing and user

POST 7.5.1 Counter Received Actions

Action Endpoints

Method	Endpoint	Description
POST	`/api/counter-received/listings/{listing_uuid}/offers/{offer_uuid}/decline`	Decline one incoming seller counteroffer
POST	`/api/counter-received/listings/{listing_uuid}/offers/{offer_uuid}/counter`	Send buyer counteroffer in the same thread
POST	`/api/counter-received/listings/{listing_uuid}/offers/{offer_uuid}/accept`	Accept incoming seller counteroffer and create accepted purchase request

Counter Request Body

{
  "offer_amount": "5950",
  "agree_terms": true
}

Accept Request Body

{
  "agree_terms": true
}

Success Response (Counter)

{
  "status": "success",
  "message": "Counteroffer sent successfully.",
  "data": {
    "uuid": "2e8bb8fd-8b5d-4dd6-8c28-0b53e12ee3f1",
    "direction": "buyer_to_seller",
    "amount_minor": 595000,
    "should_redirect_to_counters_received": true,
    "redirect_url": "/lead-trader/buy-vehicles/counters-received"
  }
}

Success Response (Accept)

{
  "status": "success",
  "message": "Counteroffer accepted successfully.",
  "data": {
    "purchase_request_id": 41,
    "status": "accepted",
    "redirect_url": "/lead-trader/buy-vehicles/pending-purchases"
  }
}

GET 7.6 Counter Offers Sent

GET https://staging.motor-space.co.uk/motorspace/api/counter-offers-sent

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Counteroffers sent loaded successfully.",
  "data": {
    "total": 1,
    "activities": [
      {
        "elapsed_time": "3h 12m",
        "next_step": "Pending response from buyer",
        "listing": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "title": "Mercedes-Benz EQA 250"
        },
        "counter_offer": {
          "uuid": "2e8bb8fd-8b5d-4dd6-8c28-0b53e12ee3f1",
          "amount_minor": 1870000,
          "decision_status": "pending"
        }
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated

Offers Sent

Authentication Required: Offers sent endpoints require a valid Sanctum Bearer token.

#	Method	Endpoint	Auth	Description
1	GET	`/api/offers-sent`	Yes	List your outgoing pending offers and pending purchase requests
2	GET	`/api/offer-sent/listings/{uuid}`	Yes	Get offer sent vehicle profile detail with editable offer payload

GET 7.1 List Offers Sent

GET https://staging.motor-space.co.uk/motorspace/api/offers-sent

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Offers sent loaded successfully.",
  "data": {
    "total": 2,
    "activities": [
      {
        "kind": "purchase",
        "remaining_time": "0h 0m",
        "remaining_minutes": 0,
        "listing": { "registration_plate": "YZ34XYZ" },
        "purchase": { "status": "pending" }
      },
      {
        "kind": "offer",
        "remaining_time": "2h 15m",
        "remaining_minutes": 135,
        "listing": { "registration_plate": "AB12CDE" },
        "offer": { "amount_minor": 1150000 }
      }
    ]
  }
}

GET 7.2 Offer Sent Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/offer-sent/listings/{uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Offer sent listing details loaded successfully.",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "registration_plate": "AB12CDE",
    "offer_sent": {
      "has_pending_purchase": false,
      "is_offer_editable": true,
      "response_window": {
        "time_limit_minutes": 240,
        "working_hours_start": "09:00",
        "working_hours_end": "17:00"
      },
      "offer": {
        "uuid": "2e8bb8fd-8b5d-4dd6-8c28-0b53e12ee3f1",
        "amount_minor": 1760000,
        "currency": "GBP",
        "buyer_vehicle_location_id": 12,
        "message": "Can you accept this?",
        "remaining_time": "2h 15m",
        "remaining_minutes": 135
      },
      "pending_purchase": null
    }
  }
}

Offers Received

Authentication Required: Offers received endpoints require a valid Sanctum Bearer token.

#	Method	Endpoint	Auth	Description
1	GET	`/api/offers-received`	Yes	List incoming pending offers and purchase requests for your listings
2	GET	`/api/offer-received/listings/{uuid}`	Yes	Get offer received listing profile detail with highest incoming offer
3	POST	`/api/offer-received/listings/{listing_uuid}/offers/*`	Yes	Accept, decline, and counter incoming offers (individual and bulk)

GET 7.1 List Offers Received

GET https://staging.motor-space.co.uk/motorspace/api/offers-received

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Offers received loaded successfully.",
  "data": {
    "total": 2,
    "activities": [
      {
        "kind": "purchase",
        "created_at": "2026-04-27T10:00:00.000000Z",
        "elapsed_time": "1h 5m",
        "next_step": "Review incoming purchase request",
        "listing": {
          "uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
          "registration_plate": "AB12CDE",
          "formatted_registration_plate": "AB12 CDE",
          "title": "Ford Transit Connect",
          "listing_price": 12750
        },
        "offer": null,
        "purchase": {
          "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
          "purchase_price_minor": 1200000,
          "status": "pending"
        }
      },
      {
        "kind": "offer",
        "created_at": "2026-04-27T08:00:00.000000Z",
        "elapsed_time": "3h 5m",
        "next_step": "Review incoming offer",
        "listing": {
          "uuid": "de9f8d7e-1234-4bcd-89ef-1234567890ab",
          "registration_plate": "YZ34XYZ",
          "formatted_registration_plate": "YZ34 XYZ",
          "title": "Vauxhall Corsa",
          "listing_price": 5500
        },
        "offer": {
          "uuid": "7a50f84c-cbe8-4f4a-9f9f-ae021e86c3a2",
          "offer_type": "first_offer",
          "direction": "buyer_to_seller",
          "amount_minor": 1150000,
          "currency": "GBP",
          "decision_status": "pending"
        },
        "purchase": null
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated

Note: This endpoint includes both incoming pending offers and buy-now purchase requests for the authenticated seller.

GET 7.2 Offer Received Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/offer-received/listings/{uuid}

Alias: /api/offer-recevied/listings/{uuid} is also supported for backward compatibility.

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Offer received listing details loaded successfully.",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "registration_plate": "YC12WSL",
    "formatted_registration_plate": "YC12 WSL",
    "title": "Ford Transit Connect 200",
    "listing_price": 6000,
    "offers": {
      "count": 2,
      "response_window": {
        "time_limit_minutes": 240,
        "working_hours_start": "09:00",
        "working_hours_end": "17:00"
      },
      "items": [
        {
          "id": 123,
          "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
          "amount_minor": 580000,
          "currency": "GBP",
          "offer_type": "counter_offer",
          "decision_status": "pending",
          "sent_at": "2026-04-28T10:15:00.000000Z",
          "window_started_at": "2026-04-28T10:15:00.000000Z",
          "remaining_time": "3h 45m",
          "remaining_minutes": 225
        },
        {
          "id": 122,
          "uuid": "2a4f83d3-d10d-4c37-93aa-2fe29f6d27e1",
          "amount_minor": 550000,
          "currency": "GBP",
          "offer_type": "first_offer",
          "decision_status": "pending",
          "sent_at": "2026-04-28T10:05:00.000000Z",
          "window_started_at": "2026-04-28T10:05:00.000000Z",
          "remaining_time": "3h 35m",
          "remaining_minutes": 215
        }
      ],
      "highest_offer": {
        "id": 123,
        "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
        "amount_minor": 580000,
        "currency": "GBP",
        "offer_type": "counter_offer",
        "decision_status": "pending",
        "sent_at": "2026-04-28T10:15:00.000000Z",
        "window_started_at": "2026-04-28T10:15:00.000000Z",
        "remaining_time": "3h 45m",
        "remaining_minutes": 225
      }
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Forbidden (listing does not belong to authenticated seller)
404	Listing not found

POST 7.3 Offer Received Actions

Action Endpoints

Method	Endpoint	Description
POST	`/api/offer-received/listings/{listing_uuid}/offers/{offer_uuid}/accept`	Accept one incoming offer and create accepted purchase request
POST	`/api/offer-received/listings/{listing_uuid}/offers/accept-highest`	Accept highest incoming offer and create accepted purchase request
POST	`/api/offer-received/listings/{listing_uuid}/offers/{offer_uuid}/decline`	Decline one incoming offer
POST	`/api/offer-received/listings/{listing_uuid}/offers/decline-all`	Decline all incoming offers for listing
POST	`/api/offer-received/listings/{listing_uuid}/offers/{offer_uuid}/counter`	Send seller counter-offer for one incoming offer
POST	`/api/offer-received/listings/{listing_uuid}/offers/counter-all`	Send same seller counter-offer to all incoming offers

Accept Request Body

{
  "agree_terms": true
}

Counter Request Body

{
  "counter_amount_minor": 575000,
  "agree_terms": true
}

Counter Notes

For counter endpoints, send counter_amount_minor in minor currency units (pence). Backward compatibility for offer_amount is still supported.

Accept Success Response

{
  "status": "success",
  "message": "Offer accepted successfully.",
  "data": {
    "purchase_request_id": 41,
    "purchase_request_uuid": "5f70412a-64f8-4a06-a0e1-a542f00d2c75",
    "listing_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "accepted"
  }
}

GET 7.4 Counter Offers Received

GET https://staging.motor-space.co.uk/motorspace/api/counter-offers-received

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Counteroffers received loaded successfully.",
  "data": {
    "total": 1,
    "activities": [
      {
        "created_at": "2026-04-28T12:28:00.000000Z",
        "elapsed_time": "1h 32m",
        "next_step": "Review incoming counteroffer",
        "listing": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "registration_plate": "AB12CDE",
          "formatted_registration_plate": "AB12 CDE",
          "title": "Volkswagen T-Roc",
          "vehicle_variant": "1.0 TSI Life 5dr",
          "listing_price": 18500
        },
        "counter_offer": {
          "uuid": "2e8bb8fd-8b5d-4dd6-8c28-0b53e12ee3f1",
          "amount_minor": 1870000,
          "currency": "GBP",
          "decision_status": "pending",
          "parent_offer_amount_minor": 1840000,
          "parent_offer_currency": "GBP"
        }
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated

Purchase Request

Authentication Required: Purchase request endpoints require a valid Sanctum Bearer token.

#	Method	Endpoint	Auth	Description
1	GET	`/api/purchase-request/listings/{uuid}`	Yes	Get seller-owned purchase-request listing detail with pending purchase request

GET 8.1 Purchase Request Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/purchase-request/listings/{uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Success Response (200)

{
  "status": "success",
  "message": "Purchase request listing details loaded successfully.",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "registration_plate": "AB12CDE",
    "formatted_registration_plate": "AB12 CDE",
    "title": "Mercedes-Benz EQA 250",
    "listing_price": 12750,
    "purchase_request": {
      "id": 41,
      "uuid": "5f70412a-64f8-4a06-a0e1-a542f00d2c75",
      "purchase_price_minor": 1275000,
      "status": "pending",
      "created_at": "2026-04-28T12:45:00.000000Z",
      "response_window": {
        "time_limit_minutes": 240,
        "working_hours_start": "09:00",
        "working_hours_end": "17:00"
      },
      "remaining_time": "3h 45m",
      "remaining_minutes": 225
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated
403	Forbidden (listing does not belong to authenticated seller)
404	Listing or pending purchase request not found

Pending Sales/Purchase Request

Authentication Required: Pending sales endpoints require a valid Sanctum Bearer token.

#	Method	Endpoint	Auth	Description
1	GET	`/api/pending-sales`	Yes	List accepted and in-progress pending sales for your listings
2	GET	`/api/pending-sales/{listing_uuid}`	Yes	Get full details of a single pending sale listing
3	POST	`/api/pending-sales/{listing_uuid}/accept`	Yes	Accept a pending purchase request for your listing
4	POST	`/api/pending-sales/{listing_uuid}/decline`	Yes	Decline a pending purchase request for your listing

GET 9.1 List Pending Sales

GET https://staging.motor-space.co.uk/motorspace/api/pending-sales

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Pending sales loaded successfully.",
  "data": {
    "total": 1,
    "activities": [
      {
        "kind": "purchase",
        "created_at": "2026-04-27T11:00:00.000000Z",
        "elapsed_time": "3h 4m",
        "next_step": "Complete pending sale",
        "listing": {
          "uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
          "registration_plate": "AB12CDE",
          "formatted_registration_plate": "AB12 CDE",
          "title": "Ford Transit Connect",
          "listing_price": 12750
        },
        "purchase": {
          "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
          "purchase_price_minor": 1200000,
          "status": "accepted"
        }
      }
    ]
  }
}

Error Responses

Status	Message
401	Unauthenticated

Note: Returns only vehicle purchases where the authenticated user is the seller and status is accepted or under_process.

GET 9.2 Pending Sale Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/pending-sales/{listing_uuid}

Returns the full vehicle listing detail plus the active purchase record for a single pending sale. The authenticated user must be the seller of the listing and a purchase with status accepted or under_process must exist.

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Description
`listing_uuid`	string (UUID)	UUID of the vehicle listing

Success Response (200)

{
  "status": "success",
  "message": "Pending sale listing details loaded successfully.",
  "data": {
    /* full vehicle listing detail (same shape as Show Listing) */
    "pending_sale": {
      "id": 42,
      "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
      "purchase_price_minor": 1275000,
      "status": "accepted",
      "status_label": "Sale Agreed",
      "next_step": "Send vehicle documents to the buyer.",
      "created_at": "2026-04-27T11:00:00.000000Z",
      "updated_at": "2026-04-27T11:30:00.000000Z"
    }
  }
}

Error Responses

Status	Message
401	Unauthenticated — missing or invalid token.
403	The listing does not belong to the authenticated user.
404	Listing not found, or no accepted/in-progress purchase exists for this listing.

POST 9.3 Accept Pending Purchase

POST https://staging.motor-space.co.uk/motorspace/api/pending-sales/{listing_uuid}/accept

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body

Field	Type	Required	Validation
`agree_terms`	boolean	Yes	Must be accepted

Success Response (200)

{
  "status": "success",
  "message": "Purchase request accepted successfully.",
  "data": {
    "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
    "listing_uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
    "status": "accepted"
  }
}

Error Responses

Status	Message
401	Unauthenticated
422	Validation failed (terms not accepted, request unavailable, or request expired)

POST 9.4 Decline Pending Purchase

POST https://staging.motor-space.co.uk/motorspace/api/pending-sales/{listing_uuid}/decline

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body

None

Success Response (200)

{
  "status": "success",
  "message": "Purchase request declined successfully.",
  "data": {
    "uuid": "3d5e83d3-d10d-4c37-93aa-2fe29f6d27e8",
    "listing_uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
    "status": "rejected"
  }
}

Error Responses

Status	Message
401	Unauthenticated
422	Validation failed (request unavailable or request expired)

Note: If no other purchase requests are in pending, accepted, or under_process state, the listing is moved back to marketplace availability.

Your Active Listings

Authentication Required: This endpoint requires a valid Sanctum Bearer token and returns only the vehicles you have listed that are currently active.

#	Method	Endpoint	Auth	Description
1	GET	`/api/active-listings`	Yes	List your own active listings
2	GET	`/api/draft-listings`	Yes	List your filtered/draft listings (draft, expired, sold, etc.)
3	GET	`/api/vehicle-listing/{listing_uuid}`	Yes	Get detailed information for one of your own listings

GET 9.1 List Your Active Listings

GET https://staging.motor-space.co.uk/motorspace/api/active-listings

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Active listings loaded successfully.",
  "data": {
    "total": 1,
    "listings": [
      {
        "id": 42,
        "uuid": "f7fe8ebf-65d1-441b-a8db-0d719e32c3a3",
        "registration_plate": "BB22BBB",
        "formatted_registration_plate": "BB22 BBB",
        "title": "Bmw 7 Series",
        "vehicle_variant": "730d xDrive M Sport 4dr Auto",
        "vehicle_status": "physical",
        "vehicle_status_label": "Physical",
        "mileage": 50000,
        "number_of_services": 5,
        "previous_owners": 2,
        "transmission": "automatic",
        "fuel_type": "Diesel",
        "colour": "Grey",
        "is_ex_taxi": false,
        "is_import": false,
        "showing_finance": false,
        "is_modified": false,
        "has_mechanical_issues": false,
        "v5_available": 1,
        "hpi_clear": true,
        "cap_valuation_clean": 25000,
        "listing_price": 24500,
        "last_registration_date": "2022-01-01",
        "tyre_report": {
          "all_over_3mm": true
        },
        "has_condition_report": true,
        "exterior_damages_count": 1,
        "interior_damages_count": 0,
        "business_location": {
          "id": 1,
          "location_name": "Main Site",
          "town_city": "London"
        },
        "submitted_at": "2026-04-16T14:00:00Z",
        "status": "active"
      }
    ]
  }
}

GET 9.2 List Filtered/Draft Listings

GET https://staging.motor-space.co.uk/motorspace/api/draft-listings

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

Request Parameters (Query)

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `draft`, `expired`, `pending_review`, `ready_to_list`, `sold`, `withdrawn`. If omitted, returns all.

Success Response (200)

{
  "status": "success",
  "message": "Listings loaded successfully.",
  "data": {
    "total": 1,
    "listings": [
      {
        "id": 43,
        "uuid": "a1b2c3d4-...",
        "registration_plate": "CC33CCC",
        "formatted_registration_plate": "CC33 CCC",
        "title": "Audi A3",
        "vehicle_variant": "1.5 TFSI Sport 5dr",
        "vehicle_status": "physical",
        "status": "draft",
        "...": "(other fields same as 9.1)"
      }
    ]
  }
}

GET 9.3 Vehicle Listing Detail

GET https://staging.motor-space.co.uk/motorspace/api/vehicle-listing/{listing_uuid}

Headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes

URL Parameters

Parameter	Type	Required	Description
`listing_uuid`	string	Yes	The UUID of the listing to retrieve.

Success Response (200)

{
  "status": "success",
  "message": "Vehicle listing details loaded successfully.",
  "data": {
    "id": 123,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "registration_plate": "AB12 CDE",
    "formatted_registration_plate": "AB12 CDE",
    "title": "BMW 3 Series",
    "vehicle_variant": "320d M Sport",
    "last_service_date": "2024-01-15",
    "mileage": 45000,
    "transmission": "Automatic",
    "fuel_type": "Diesel",
    "colour": "Black",
    "photos": [
      {
        "id": 1,
        "uuid": "...",
        "url": "https://staging.motorspace.co.uk/...",
        "sort_order": 1
      }
    ],
    "exterior_damages": [
      {
        "id": 1,
        "location_title": "Front Bumper",
        "description": "Small scratch on passenger side",
        "photos": [{"url": "..."}]
      }
    ],
    "interior_damages": [],
    "tyre_report": {
      "all_over_3mm": true,
      "offside_front_tread": "4mm",
      "has_spare_wheel": true
    },
    "mechanical_issues": {
      "has_issues": false,
      "description": null
    },
    "status": "active"
  }
}

Reference Data

#	Method	Endpoint	Auth	Description
1	GET	`/api/body-types`	No	List all vehicle body types

GET 10.1 List Body Types

GET https://staging.motor-space.co.uk/motorspace/api/body-types

Request Parameters

None

Success Response (200)

{
  "status": "success",
  "message": "Body types loaded successfully.",
  "data": [
    {
      "id": 1,
      "name": "Hatchback",
      "slug": "hatchback",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z"
    }
  ]
}

Note: Results are returned in insertion order. No authentication required.

Signup Flow

The complete signup flow follows these steps in order:

1POST /api/signup/about-you

→

2POST /api/signup/verify-otp

→

3POST /api/signup/update-info

→

4POST /api/accept-terms

→

5POST /api/login

Step	Endpoint	Purpose
1	`POST /api/signup/about-you`	Register account and receive OTP
2	`POST /api/signup/verify-otp`	Verify email with OTP
3	`POST /api/signup/update-info`	Complete profile details
4	`POST /api/accept-terms`	Accept terms and conditions
5	`POST /api/login`	Login to get access token

Password Reset Flow

The password reset flow follows these steps:

1POST /api/forgot-password

→

2POST /api/forgot-password/verify-otp

→

3POST /api/reset-password

Step	Endpoint	Purpose
1	`POST /api/forgot-password`	Request OTP via email
2	`POST /api/forgot-password/verify-otp`	Verify OTP
3	`POST /api/reset-password`	Set new password with token

Vehicle Registration Flow

The complete vehicle registration flow follows these steps in order:

1GET reference-data

→

2POST lookup

→

3POST confirm-derivative

→

4POST listings

→

5POST exterior-damages

→

6POST interior-damages

→

7PUT tyre-report

→

8PUT mechanical-report

→

9POST additional-info

→

10PUT pricing

Step	Endpoint	Purpose
1	`GET /api/register-vehicle/reference-data`	Load dropdown options (body types, fuel types, etc.)
2	`POST /api/register-vehicle/lookup`	Lookup vehicle details by registration number
3	`POST /api/register-vehicle/confirm-derivative`	Confirm selected derivative (if alternatives exist)
4	`POST /api/register-vehicle/listings`	Create the vehicle listing with all details
5	`POST /api/register-vehicle/listings/{id}/exterior-damages`	Report any exterior damage (repeatable)
6	`POST /api/register-vehicle/listings/{id}/interior-damages`	Report any interior damage (repeatable)
7	`PUT /api/register-vehicle/listings/{id}/tyre-report`	Submit tyre condition report
8	`PUT /api/register-vehicle/listings/{id}/mechanical-report`	Submit mechanical condition report
9	`POST /api/register-vehicle/listings/{id}/additional-info`	Add extra notes and photos
10	`PUT /api/register-vehicle/listings/{id}/pricing`	Set the listing price and finalize

MotorSpace API Documentation — Last updated: April 24, 2026